superdev-cli 0.1.0

package/skills/resume/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: resume
+description: Rebuild working context from the Superdev database after a break, a new session, a handoff, or a compaction. Use for "continue where we left off", "pick up yesterday's work", "resume", "what was I doing?", or at the start of any session where a lifecycle hook did not run. Loads the active task, its feature and contract, governing decisions, blockers, pending documentation proposals and the recorded next action, searches local memory for the session outcome and handoff, verifies all of it against the live repository, and proposes the exact next action. Reads from records rather than from a memory of the previous conversation.
+---
+
+# Resume
+
+The next agent resumes from the database, not from the conversation. Anything
+you cannot trace to a record or to live repository evidence is a guess, and it
+gets labeled as one.
+
+`SD` means the installed `superdev` command, with `--root <project>` on
+every call.
+
+## Steps
+
+1. **Load the handoff.** `SD resume --json`. It carries the current objective,
+   the active task and feature, the last verified result, branch and HEAD,
+   decisions encountered, blockers, scope changes, pending documentation
+   updates, and the exact next action.
+2. **Load the surrounding state.** `SD status --json` for progress and open
+   work. `SD task show <TASK-id>` for the active task's contract links,
+   dependencies, activity and evidence.
+3. **Search memory for context the records do not carry.**
+   `SD memory search "<topic>"` returns session outcomes, facts,
+   blockers, questions and handoffs, with their links. Memory is recall, not
+   authority: verify a recalled fact against the current specification,
+   decision, code or evidence before acting on it, and say which check you ran.
+4. **Verify against live reality.** Does HEAD match what the record says was
+   verified? Are the files a completion claimed present? Did anything change
+   outside Superdev (new commits, dirty worktree, a dependency bump)? Report
+   every discrepancy as drift. Never reconcile it silently.
+5. **Check what accumulated while you were away.** `SD docs diff` for pending
+   proposals, blocked tasks, and owner questions answered or still open.
+6. **Reconstruct the working frame** out loud: objective, active task, the
+   contract it implements, the decisions that govern it, what is blocked, and
+   what verification the task requires.
+7. **Propose the next action**: the recorded one, revalidated. If it no longer
+   applies, say why and propose the corrected step.
+8. **Confirm before implementing** when anything material drifted since the
+   record was written.
+
+## If there is no active assignment
+
+Do not invent one. Report what the project's next action is, offer the ready
+work from `SD task list --status ready`, and let the person choose. Then run the
+before-implementation sequence from the `task` skill before touching code.
+
+## Harness reality
+
+- On Claude Code, the session-start hook already shows the active task. Running
+  `SD resume` is still correct; it is cheap and it is the same source.
+- On Codex, hooks fire only if the user has trusted them, so assume they did
+  not and run `SD resume` explicitly.
+- On skills.sh there is no lifecycle hook at all. `SD resume` is the only way
+  the context arrives.
+
+Correctness never depends on a hook having fired. Say which command you ran.
+
+## Providers
+
+Claude Mem, when installed, may supplement recall of earlier conversations. It
+is a cache and never project authority: every recalled fact is verified against
+the database or the repository before consequential use, and recall-sourced
+claims carry their verification status. If it is not installed, resume from the
+database alone and say so. Do not credit it when it did not run.
+
+## Boundaries
+
+- Read only until the person confirms the resumed direction.
+- Everything asserted must trace to a named record or a named piece of live
+  evidence. Fresh-session accuracy is this skill's whole job.
+- Never reconstruct state by re-reading old conversation summaries when a record
+  exists that answers the same question.
+
+*Standalone note: on skills.sh, install the generated `superdev` package. It
+carries the orchestrator, the Docs capability and the runtime, and needs no
+repository. A single skill copied out on its own has no runtime; say which
+command was unavailable rather than working around it silently.*

package/skills/review/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: review
+description: Review a change in two stages, first whether it matches what was accepted, then whether the code is any good. Use for "review this", "review the PR", "check this against the spec", "is this ready to merge?", or before completing substantial work. Stage one compares the diff against the task's contract links, the feature's acceptance criteria and the governing decisions, and flags behavior that nobody specified. Stage two covers correctness, security, error handling, product tests and maintainability. Every finding carries a severity, a concrete failure scenario, a location, the requirement it affects, a remediation and a confidence. Reports findings; applies fixes only when asked.
+---
+
+# Review
+
+A change that perfectly implements the wrong thing still fails. Stage one runs
+first, always.
+
+`SD` means the installed `superdev` command, with `--root <project>` on
+every call.
+
+## Stage one: contract compliance
+
+1. **Find the governing contract.** `SD task show <TASK-id>` gives the task, its
+   feature, and the exact contracts it links: workflow steps, UI actions, API
+   operations, data entities, migrations, integrations, jobs, webhooks, NFRs,
+   documents, decisions. That link set is the specification for this diff.
+   No task means the work skipped the before-implementation sequence, which is
+   itself a finding.
+2. **Check the acceptance criteria** of the feature the task belongs to. Each
+   one either has evidence in this change or is explicitly out of scope for this
+   task.
+3. **Check the governing decisions.** `SD decision list --json`. A change that
+   violates an active decision is a P0 finding and routes to the `decision`
+   skill, never a quiet exception.
+4. **Look for unspecified behavior in the diff.** New behavior nobody accepted
+   needs a specification through the `feature` skill or an explicitly recorded
+   bypass with owner, reason, scope and expiry. Side effects that were never
+   requested are findings, not bonuses.
+5. **Check the documentation projection.** `SD docs diff`. A pending proposal
+   means the docs and the database disagree, and merging on top of that hides
+   the disagreement.
+
+## Stage two: code quality
+
+Review the diff plus enough surrounding code to judge it:
+
+- correctness defects, including the paths the change did not touch but affects;
+- security: trust boundaries, injection, authorization, secret handling;
+- error handling and data-loss paths;
+- product tests: missing, weakened, or asserting the implementation rather than
+  the behavior;
+- convention violations against this repository, not against a general
+  preference;
+- complexity beyond the smallest sufficient solution.
+
+For products built with Superdev, the expected tests come from the accepted
+product test plan. Never require tests for the Superdev plugin itself: it has
+none, by design.
+
+## Finding format
+
+Every finding, both stages:
+
+**Severity** (P0 blocks, P1 should fix, P2 improvement) followed by a **concrete
+failure scenario** (inputs and state leading to the wrong outcome; no scenario,
+no finding), **file and line**, the **requirement or contract affected**, a
+**remediation**, and your **confidence**.
+
+A finding without a failure scenario is a preference. Say so, or drop it.
+
+## Providers
+
+Route review discipline to **Superpowers** (its code review and receiving-review
+workflows) and, for interface work, critique and accessibility to **Impeccable**.
+Check readiness with `SD doctor`. If a provider is not ready, apply this
+contract directly and say plainly that the specialist pass did not run. Never
+present your own checklist as theirs.
+
+## After the review
+
+- Findings that survive verification block completion of the work under review.
+  Record them: `SD task evidence <TASK-id> --summary "<the P0 and P1 findings>" --result fail`, or
+  `SD task block <TASK-id> --reason <why>` when the work cannot proceed.
+- When the change is accepted, completion still needs its evidence through
+  `SD task complete`. A passing review is one kind of evidence, not a substitute
+  for the product's own verification.
+
+## Boundaries
+
+- Report findings; apply fixes only when asked.
+- State honestly what was reviewed and what was not: paths, depth, generated
+  code skipped, anything you could not run.
+- Never approve on the basis of a check you did not actually run.
+
+*Standalone note: on skills.sh, install the generated `superdev` package. It
+carries the orchestrator, the Docs capability and the runtime, and needs no
+repository. A single skill copied out on its own has no runtime; say which
+command was unavailable rather than working around it silently.*

package/skills/status/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: status
+description: Report where the project actually stands, from the Superdev database. Use for "where are we?", "what is done?", "what is blocked?", "what is left?", "show me progress", "is anything stale?", or before a handoff, a standup or a release conversation. Reads active work, progress with the counts behind it, blockers, open owner questions, capability areas awaiting a decision, pending documentation proposals, evidence freshness and the next action, then reports them in plain language. Read only, so it changes no record, and it never states a percentage the accepted contract does not support.
+---
+
+# Project Status
+
+Report the truth, including the parts nobody wants to hear. Every number comes
+from the database and can explain itself.
+
+`SD` means the installed `superdev` command, with `--root <project>` on
+every call.
+
+## Steps
+
+1. **Read the status.** `SD status --json`. It carries active work, progress per
+   feature, module, milestone and goal, blockers, freshness and the derived next
+   action. If there is no project in the database, say so and offer `init`
+   rather than describing a project that does not exist.
+2. **Check the database is sound.** `SD db status` runs the integrity and
+   foreign-key check. A failing integrity check is the headline, not a footnote.
+3. **Check for pending documentation proposals.** `SD docs diff`. A manual edit
+   to generated Markdown is waiting for review, and until it is reviewed the
+   docs and the database disagree.
+4. **Check open owner questions and unresolved capability areas.** An area
+   awaiting a decision is unfinished planning, not a blank.
+5. **Cross-check against live reality.** Current branch and HEAD, dirty files,
+   whether the evidence behind recent completions still matches what is on disk.
+   Report a disagreement as a disagreement; never reconcile it silently.
+6. **Report** in the shape below.
+
+## What to report
+
+- **Where the project stands**: completed and total per applicable component,
+  with what counts and what remains.
+- **Active work**: the claimed task, its feature, who or what holds it, and how
+  long it has been held.
+- **Blocked work**, each with what would unblock it.
+- **Open owner questions** and capability areas awaiting a decision.
+- **Pending documentation proposals** from `docs diff`.
+- **Freshness**: database revision, last event sequence, last documentation
+  generation, active session heartbeat, branch HEAD, stale evidence.
+- **The next action**: exactly one, and say why it is next.
+
+Lead with what matters. A wall of counts is not a status report.
+
+## Progress honesty
+
+Progress is derived from the accepted product contract, and one implementation
+computes it for both the command line and the control center. They cannot
+disagree.
+
+- Only applicable components count. A backend feature with no interface is not
+  permanently short one component.
+- A record with no declared completion contract reports **Not measurable**.
+  Never zero, never one hundred percent.
+- Every value carries its completed count, total count, what counts, what
+  remains, source revision and freshness. A bare percentage is not a valid
+  answer.
+- Cancelled and superseded work leaves the totals and stays visible in history.
+- Evidence older than thirty days is **stale**, which is not the same as
+  satisfied.
+
+Never fabricate progress for a record the database has no contract for, and
+never average unrelated numbers into one comforting figure.
+
+## Seeing it
+
+`SD ui` opens the control center, which shows the same data live and updates
+from committed transactions. Offer it whenever the answer is more than a
+paragraph, or when someone wants the blueprint, workflow, data or readiness
+views rather than prose.
+
+## Boundaries
+
+- Read only. This skill changes no record and repairs nothing while reporting.
+  A repair routes to `task`, `decision`, `feature` or `docs`.
+- Never state a percentage the accepted contract does not support.
+- Never present the absence of a record as the absence of the problem. Say what
+  is unknown and what would make it known.
+
+*Standalone note: on skills.sh, install the generated `superdev` package. It
+carries the orchestrator, the Docs capability and the runtime, and needs no
+repository. A single skill copied out on its own has no runtime; say which
+command was unavailable rather than working around it silently.*

package/skills/task/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: task
+description: Run the task lifecycle against the Superdev database. Use for "what should I work on?", "what am I working on?", "create a task for this", "claim this", "this is blocked", "mark it done", "reopen that", "break this into subtasks", or when a task creation is refused because it has no feature or no contract behind it. Covers deriving tasks from accepted specifications, the find-or-create then link then claim sequence before implementation, recording activity, blocking and unblocking, completing with evidence, reopening with history, and the dependency and subtask graph. Does not run the feature interview, and an unspecified feature routes to the feature skill first.
+---
+
+# Task Lifecycle
+
+Task tracking is an execution contract, not a status report written afterwards.
+Every task lives in the database at `.superdev/superdev.db`. There is no task
+file, and there never will be: one file per row is the failure this design
+exists to remove.
+
+`SD` means the installed `superdev` command, with `--root <project>` on
+every call. Full surface:
+`the plugin's skills/project/references/commands.md`.
+
+## The two rules the database enforces
+
+1. **Every task belongs to exactly one feature.** `feature_id` cannot be null.
+2. **Every task either links a contract or is explicitly enabling.** Contract
+   kinds: workflow step, UI action, API operation, data entity, migration,
+   integration, job, webhook, NFR, document, accepted decision. Enabling work
+   must name the feature it unblocks in plain language.
+
+These are triggers, not advice. Refusals:
+
+| Code | What it means | What to do |
+|---|---|---|
+| `E_TASK_WITHOUT_CONTRACT` | The task implements nothing that was specified | Link the contract, or specify it first through the `feature` skill |
+| `E_ENABLING_WITHOUT_TARGET` | Enabling work naming no unblocked feature | Add `--enabling --unblocks <FEAT-id>` and say why in the outcome |
+| `E_OPEN_SUBTASKS` | A parent cannot close over open required children | Close or cancel the children, or remove the requirement deliberately |
+| `E_VERSION_CONFLICT` | The record changed under you | Re-read with `task show` and retry |
+| `E_DB_LOCKED` | Another process holds the write lock | Retry. Never remove a lock by hand |
+
+A refusal is information: the work is not yet understood well enough to start.
+Do not route around it by inventing a feature or a link.
+
+## Deriving work
+
+Tasks are derived from accepted specifications, never invented from a feature
+title.
+
+```
+SD derive <FEAT-id>
+```
+
+Derivation reads acceptance criteria, workflow steps, surfaces and UI actions,
+API operations, data entities and migrations, integrations, jobs and webhooks,
+permissions, NFRs, observability, the product test plan, documentation
+synchronization, and rollout and rollback.
+
+- Outcome sized: assignable, implementable, verifiable.
+- Not one task per row. Combine what must change together, split what can be
+  delivered or blocked on its own.
+- Subtasks only where they improve execution clarity.
+- **Present the derived plan for acceptance before any of it is implemented.**
+- A scope change updates the specification first, then regenerates a delta.
+- Product test work comes from the accepted product test plan. Never create a
+  test task for the Superdev plugin itself.
+
+## Before implementation
+
+The sequence, in order:
+
+```
+SD task list --status ready --json          # 1. is there already a task
+SD task create --feature <FEAT-id> --name <t> \
+  --link <kind>:<id>                             # 2, 3, 4. draft it with its contract
+SD decision list --json                          # 6. governing decisions
+SD task claim <TASK-id>                          # 7. developer, agent, branch, session
+SD task update <TASK-id> --status in_progress    # 8.
+```
+
+Step 5 has no command: if the feature does not exist, stop and specify it
+through the `feature` skill. Implementation waits.
+
+Claim exactly one active task at a time. If a second piece of work appears
+mid-flight, it is either in scope for the current task (update it) or a new task
+(create it and leave it Ready).
+
+## Status model
+
+Draft, Ready, In Progress, In Review, Verifying, Blocked, Paused, Complete,
+Cancelled, Superseded.
+
+- Status history is append-only. Nothing is edited into a different past.
+- Parent status is derived. A parent never completes while required child work
+  is open or verification is missing.
+- Move with `SD task update <TASK-id> --status <status>`.
+
+Categories are data, not constants: Feature, Improvement, Bug, Refactor,
+Investigation, Documentation, Integration, Migration, Infrastructure, Security,
+Quality, Backlog. A project may add its own. An unclassified historical task
+displays as Unclassified until someone classifies it deliberately.
+
+## During the work
+
+- `SD task evidence <TASK-id> --summary "<what changed and why>"` at natural
+  boundaries. Every mutation already writes an activity event, so a note is for
+  what a human would want to read later, not for narrating tool calls.
+- Scope grew? Update the task and the specification before continuing.
+- `SD task block <TASK-id> --reason <why>` the moment something blocks, with
+  what would unblock it. A blocker discovered at the end of a session was
+  unrecorded for the whole session.
+- Dependencies: a task that must wait names what it waits for, so the graph and
+  not a memory decides the order.
+
+## Completing
+
+```
+SD task evidence <TASK-id> \
+  --summary <what was observed> \
+  --result <pass|fail|inconclusive> \
+  --type <validator|command|review|manual_check> \
+  --reference <path or command> \
+  --command <the check, re-runnable> \
+  --criterion <AC-id, when it proves one> \
+  --plan <TP-id, when it is a run of an accepted test plan>
+SD task complete <TASK-id>
+```
+
+Record `--command` whenever a command proved it, so `SD verify` can re-run the
+check later and mark the evidence stale if it stops passing. Leave it off when
+nothing reproduces the check; a manual verification is honest, an invented
+command is not.
+
+Completion is refused until every verification requirement the task states
+carries its own passing evidence, so `task evidence` runs once per requirement
+and `task complete` comes last. Section 9.3 also requires the accepted test
+plans covering the work to have passed: `SD test-plan list` shows which cover
+it and whether each has a passing run, `SD test-plan run <TP-id>` runs the ones
+that are commands, and `SD test-plan record <TP-id> --summary` records a journey
+that was carried out rather than run. An acceptance criterion that will not be
+met is set aside with `SD feature waive <AC-id> --reason`, never left silently
+unmet. A requirement you could not run takes
+`--result inconclusive`, which records the attempt and leaves the task open.
+
+Before that call:
+
+1. Run the product's required verification and read the output. Never attach
+   evidence for a run you did not observe.
+2. Update affected docs: `SD docs generate`, then `SD docs diff` for pending
+   proposals.
+3. Confirm the related acceptance criteria are genuinely satisfied.
+4. Complete or reopen dependent work as the graph requires.
+
+Completion releases the assignment and recalculates parent progress from the
+accepted contract. Evidence older than thirty days is stale, which is not the
+same as satisfied.
+
+## Reopening and superseding
+
+- `SD task reopen <TASK-id> --reason <why>` when completed work turns out not to
+  hold. History is preserved; the earlier completion and its evidence stay
+  visible.
+- Work that no longer applies is cancelled or superseded, with the successor
+  named. Never silently rewrite a completed task into a different task.
+
+## Reading the board
+
+- `SD task list --status <status>` filters the board.
+- `SD task list --feature <FEAT-id>` shows one feature's work.
+- `SD task list --all` includes work that is not Ready. Claims show in the
+  listing, so what this developer or agent holds is read from there.
+- `SD task show <TASK-id>` gives contract links, dependencies, subtasks,
+  activity and evidence.
+- `SD ui` opens the same data in the control center, live.
+
+## Boundaries
+
+- Never mark a task complete to make a report look finished. Completion is
+  evidence.
+- Never create a task that exists only to satisfy tracking. If it implements
+  nothing specified and unblocks nothing, it should not exist.
+- Never put secrets, personal data or absolute machine paths into a task, a
+  note, or an evidence reference.
+- Task detail belongs in the database and the control center, not in a Markdown
+  file. Do not generate one.
+
+*Standalone note: on skills.sh, install the generated `superdev` package. It
+carries the orchestrator, the Docs capability and the runtime, and needs no
+repository. A single skill copied out on its own has no runtime; say which
+command was unavailable rather than working around it silently.*