Add living-spec workflow for solo product documentation

COVERAGE.md

@@ -2,9 +2,9 @@
 
 This pack aims for **full upstream pstack capability coverage**, ported to Agent Skills + adapters.
 
-## Skills (45)
+## Skills (46)
 
-All upstream skills under `skills/` plus the portable hub `pstack`.
+All upstream skills under `skills/` plus the portable additions `pstack` and `living-spec`.
 
 ## Playbooks (23)
 
@@ -27,6 +27,10 @@ Mirrored in `skills/poteto-mode/playbooks/` and `skills/pstack/playbooks/`.
 | poteto-mode `scripts/` (orch, watch-pr) | omitted from pack copy (Cursor tooling); playbooks note fallbacks |
 | benny automations | kept under `references/automations/benny/skill-templates/` as `INSTRUCTIONS.md` (not discoverable by `npx skills add`) |
 
+## Portable-only additions
+
+`living-spec` adds an optional current-product-truth workflow for solo projects. It is intentionally not part of upstream pstack and does not replace OpenSpec or another repository-native specification system.
+
 ## External (never in upstream pstack either)
 
 `deslop`, `control-cli`, `control-ui` from `cursor-team-kit`.

README.md

@@ -19,7 +19,7 @@ See [INSTALL.md](./INSTALL.md) for per-agent selection, optional skills.sh insta
 | Area | Skills and assets |
 | --- | --- |
 | Entry | `pstack`, `poteto-mode` |
-| Workflow | `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `figure-it-out`, `teach`, `reflect`, `automate-me`, `setup-pstack`, `show-me-your-work`, `create-verification-skill`, `maintain-verification-skill`, `tdd`, `typescript-best-practices` |
+| Workflow | `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `figure-it-out`, `teach`, `reflect`, `automate-me`, `setup-pstack`, `show-me-your-work`, `living-spec`, `create-verification-skill`, `maintain-verification-skill`, `tdd`, `typescript-best-practices` |
 | Quality | `unslop`, `no-comments`, `technical-writing`, `bro` |
 | Principles | all 21 `principle-*` leaf skills |
 | Playbooks | 23 mirrored under `skills/poteto-mode/playbooks/` and `skills/pstack/playbooks/` |
@@ -38,6 +38,16 @@ See [INSTALL.md](./INSTALL.md) for per-agent selection, optional skills.sh insta
 
 The portable layer is an instruction protocol, not an emulator. It preserves workflow intent across hosts, but it cannot manufacture features a host does not expose. A runtime without subagents, model selection, browser control, or persistent modes will use the documented fallback and state the limitation.
 
+## Living product documentation
+
+`living-spec` is an optional, solo-friendly documentation layer for projects that use pstack without a full specification framework. It keeps three concerns separate:
+
+- `docs/product/` describes the product's current, verified behavior;
+- `docs/changes/` holds a temporary brief only for changes that span sessions, pull requests, or several modules;
+- `docs/decisions/` records durable, non-obvious technical decisions with meaningful alternatives.
+
+The skill does not require documentation for internal refactors or trivial edits. It first inspects the repository for an existing canonical system such as OpenSpec, ADRs, or product docs, and reuses that system instead of creating a competing source of truth. Feature work converges documentation only after real-surface verification.
+
 ## Session and mode behavior
 
 `/poteto-mode` is sticky when the active host supports persistent skill or mode state. On hosts without that lifecycle, treat it as active for the current conversation and invoke it again after a fresh session or a context reset. The engineering rules and playbooks remain portable even when the host cannot provide a native mode flag.

UPSTREAM_MANIFEST.json

@@ -13,6 +13,7 @@
     "capability_contract_version": "1.0.0",
     "hand_maintained_skills": [
       "pstack",
+      "living-spec",
       "poteto-mode",
       "how",
       "why",

skills/living-spec/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: living-spec
+description: "Maintain a lightweight, current product-truth layer for pstack projects. Use for /living-spec inspect, draft, or converge; when a feature changes durable user-visible or business behavior; when work spans sessions or pull requests; or when current product docs, change briefs, or ADRs must stay aligned with verified implementation."
+license: MIT
+compatibility: Works with Agent Skills-compatible coding agents. Multi-agent optional; see pstack adapters.
+---
+
+# Living spec
+
+Keep the repository's current product behavior understandable without requiring a full specification framework for every task.
+
+This skill is intentionally small. It distinguishes:
+
+- **current truth** — what the product now promises;
+- **change context** — what one in-progress change is trying to alter;
+- **decision rationale** — why one durable technical choice won;
+- **execution evidence** — how the work was performed and verified.
+
+Do not combine those into one ever-growing document.
+
+## Portability (required)
+
+1. Read the [pstack capability contract](../pstack/references/capability-contract.md), [workflow-quality defaults](../pstack/references/workflow-quality.md), and the active host adapter before delegation.
+2. Use `explore` to discover existing documentation and behavior, `implement` for bounded documentation edits, `review` for independent convergence checks, `ask_user` only for product intent that evidence cannot settle, and `verify` for observable behavior.
+3. Keep paths repository-relative. Do not depend on one vendor's session, transcript, or rules directory.
+4. Small documentation decisions stay on the lead agent. Use helpers only when independent investigation or review will reduce a real blind spot.
+5. Existing canonical systems win. If the repository already uses OpenSpec, another spec framework, established ADRs, or a product documentation hierarchy, update that system instead of creating a competing source of truth.
+
+## Default layout
+
+Use the repository's established layout when one exists. Otherwise prefer:
+
+```text
+docs/
+├── product/      # current verified product behavior
+├── changes/      # temporary briefs for larger in-progress changes
+└── decisions/    # durable ADRs
+
+.audit/            # optional execution evidence from show-me-your-work
+```
+
+These paths are defaults, not requirements.
+
+## Persistence decision
+
+At the beginning of a feature, classify the change with these questions:
+
+1. Does it create or modify durable user-visible, operator-visible, API, security, billing, permission, data-retention, or business behavior?
+2. Will it likely span multiple sessions, pull requests, repositories, owners, or independently shipped units?
+3. Will a future maintainer need to know why a non-obvious choice was made?
+
+Choose the smallest persistence level that earns its cost:
+
+| Result | Action |
+| --- | --- |
+| No durable behavior change | No product document. Record `not required` with a reason. |
+| Durable behavior, one bounded change | Update one current-truth product document during `converge`. |
+| Durable behavior plus multi-session or multi-PR work | Create one temporary change brief, then converge into current truth. |
+| Durable, non-obvious, hard-to-reverse decision with real alternatives | Add an ADR in addition to the relevant current-truth update. |
+
+Do not create an ADR for naming, local refactoring, routine library use, or an easily reversible implementation detail.
+
+## Operation: inspect
+
+Use before design or implementation.
+
+1. Read the user request, originating ticket/spec/acceptance list, and relevant repository instructions.
+2. Discover existing product docs, specifications, ADR conventions, change briefs, and external authority documents.
+3. Use `explore` to compare intended behavior with current code, tests, and the real runtime surface when available.
+4. Classify any mismatch:
+   - **implementation bug** — documented or requested behavior is not delivered;
+   - **stale documentation** — verified behavior changed intentionally but current truth was not updated;
+   - **unresolved product decision** — evidence cannot determine what should happen;
+   - **implementation detail only** — no product-truth update is needed.
+5. Return a documentation plan:
+   - persistence level;
+   - canonical files to read or update;
+   - whether a change brief is warranted;
+   - whether an ADR may be warranted;
+   - explicit `not required` reason when no persistence is needed.
+
+`inspect` is read-only unless the user explicitly asks to create the brief immediately.
+
+## Operation: draft
+
+Use only when `inspect` found that the change benefits from a persistent brief.
+
+1. Create one file using the [change brief template](references/change-brief-template.md).
+2. Keep it concise: intent, scope, non-goals, acceptance, constraints, current design choice, verification plan, and product docs expected to change.
+3. Prefer checkable behavior over implementation narration.
+4. Link authoritative security, design-system, API, or operational docs rather than copying them.
+5. Set status to `draft` or `in-progress`. The brief is not current product truth.
+6. When implementation reveals a real design change, update the brief rather than allowing chat history to become the only record.
+
+Do not split a solo-project change into proposal/spec/design/tasks files unless the repository already follows that convention.
+
+## Operation: converge
+
+Use only after the implementation has been verified on the meaningful real surface.
+
+1. Re-read:
+   - the original intent and acceptance criteria;
+   - the final implementation diff;
+   - tests and runtime evidence;
+   - any change brief and decision trail;
+   - current product docs and ADRs.
+2. Update current truth using the [product document template](references/product-doc-template.md), adapted to the repository's existing style.
+3. Describe the final verified behavior:
+   - normal paths;
+   - failure and boundary scenarios;
+   - product constraints and non-goals that remain relevant;
+   - stable technical constraints only when maintainers must preserve them;
+   - repeatable verification surfaces.
+4. Remove or rewrite stale current-behavior statements. Never append a new rule beside a contradictory old rule.
+5. Do not rewrite desired intent to match a broken implementation. When verified behavior misses the accepted requirement, report a convergence gap and route back to implementation or an explicit product decision.
+6. Create an ADR from the [ADR template](references/adr-template.md) only when the decision is durable, non-obvious, difficult to reverse, and had meaningful alternatives.
+7. Resolve the temporary change brief:
+   - archive it when its decision history remains valuable;
+   - otherwise delete it after current truth converges; Git retains the history;
+   - never leave an `in-progress` brief after the change is complete.
+8. Run a convergence review:
+   - for ordinary work, the lead compares docs, acceptance, diff, and verification;
+   - for high-risk or broad changes, use one read-only `review` helper with `model_role:critic`;
+   - classify the result as `pass`, `gap`, or `not applicable`.
+
+## Canonicality rules
+
+- One domain has one current-truth home.
+- Current product docs describe **now**, not the chronology of implementation.
+- Change briefs describe **this in-progress change**, not the whole product.
+- ADRs describe **why a durable decision was made**, not product requirements.
+- `.audit/` and `show-me-your-work` describe **execution evidence**, not current behavior.
+- Git history preserves previous versions; do not retain obsolete rules in current docs merely for history.
+- External authority documents stay authoritative. Link them and record only the change-specific constraint.
+
+## Output contract
+
+Always report:
+
+```text
+Documentation:
+- persistence: none | product-doc | change-brief | ADR
+- current truth: <paths or not required>
+- change brief: <path and status, or none>
+- decisions: <ADR paths or none>
+- convergence: pass | gap | not applicable
+- evidence: <verification pointers>
+```
+
+When there is a gap, name whether code, docs, or product intent must change next.

skills/living-spec/references/adr-template.md

@@ -0,0 +1,35 @@
+# ADR-<number>: <Decision title>
+
+Status: proposed
+
+## Context
+
+What durable problem or constraint made a decision necessary. Explain why the choice is non-obvious to a future maintainer.
+
+## Decision
+
+State the selected option and the boundary it establishes.
+
+## Alternatives
+
+### <Alternative>
+
+Why it was viable and why it was rejected.
+
+### <Alternative>
+
+Why it was viable and why it was rejected.
+
+## Consequences
+
+- Benefits gained.
+- Costs and constraints accepted.
+- Migration, ownership, compatibility, or operational effects.
+
+## Verification
+
+Evidence that the selected decision works on the intended surface.
+
+## Revisit when
+
+Concrete conditions that would justify reopening the decision.

skills/living-spec/references/change-brief-template.md

@@ -0,0 +1,41 @@
+# Change: <Title>
+
+Status: draft
+
+## Intent
+
+Why this change matters and which user, operator, or business outcome it improves.
+
+## Scope
+
+- Behavior included in this change.
+
+## Non-goals
+
+- Related behavior intentionally excluded.
+
+## Acceptance
+
+- [ ] One observable success or failure scenario per item.
+
+## Constraints
+
+- Product, security, compatibility, operational, dependency, or migration constraints that control the work.
+- Link authoritative documents instead of duplicating them.
+
+## Design
+
+The current selected approach, key data shape, ownership boundaries, and important trade-off. Update this section when implementation evidence changes the design.
+
+## Decisions
+
+- Decision — reason — evidence.
+- Keep only decisions another session would need.
+
+## Verification plan
+
+- Real surfaces and checks that will prove the accepted behavior.
+
+## Product docs to update
+
+- `docs/product/<domain>.md` or the repository's existing canonical equivalent.

skills/living-spec/references/product-doc-template.md

@@ -0,0 +1,35 @@
+# <Domain>
+
+## Purpose
+
+One paragraph describing the user, operator, or business outcome this domain owns.
+
+## Current behavior
+
+- Describe behavior that is true in the verified product now.
+- Use stable language that survives implementation refactors.
+- Split unrelated behavior into separate bullets or subsections.
+
+## Failure and boundary scenarios
+
+- Describe important rejected, unavailable, expired, partial, or recovery paths.
+- Include security, permission, billing, data-loss, and compatibility boundaries when relevant.
+
+## Product constraints
+
+- State durable in-scope and out-of-scope behavior.
+- Do not list temporary implementation tasks.
+
+## Technical constraints
+
+Include only constraints future maintainers must preserve, such as an external protocol, storage ownership rule, migration invariant, or public compatibility contract.
+
+## Verification surfaces
+
+- Name repeatable UI, CLI, API, test, trace, or operational checks that prove the behavior.
+- Prefer concrete paths or commands when stable.
+
+## Related decisions
+
+- Link relevant ADRs.
+- Link external authoritative documents rather than copying them.