@dezycro-ai/agent-plugin 2.0.0

package/skills/author/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: author
+description: Author or revise a Dezycro PRD or TRD via the V2 guided flow — discovery, clarifying Q&A, drafting, and quality gates. Use when the user wants to write or significantly revise a PRD or TRD for a feature. Accepts an optional feature name or UUID and flags `--doc prd | --doc trd` and `--revise-existing`.
+---
+
+# Author PRD/TRD (V2 Guided Flow)
+
+You are walking the user through guided authoring of a Dezycro PRD or TRD. The driver is a state machine; you persist transitions and the QA transcript so the loop survives compaction.
+
+## Hard Rules — Read Before Anything Else
+
+1. **No TRD without an APPROVED PRD.** Per EC-14 — refuse early in `DETECT_INTENT` if the feature has no PRD or the PRD is not `APPROVED`. Offer to author the PRD first.
+2. **TRD quality gate is non-negotiable.** Deterministic checks + P-9 reviewer must both pass before `change_document_status(trdId, APPROVED)`. The `PreToolUse:change_document_status` hook will block the call belt-and-suspenders.
+3. **Min-context gate is non-negotiable.** `MIN_CONTEXT_GATE` must pass deterministic checks AND P-7 before drafting a TRD.
+4. **Suppress pillar-3 auto-logging while authoring.** Always start the session by calling `companion-runner authoring-state --set=enter ...`. The Stop hook reads `companion-state.json:authoringMode` and skips the workbook sweep. Always call `--set=exit` on FINALIZE / cancel.
+5. **Intent statements during authoring DO NOT go to the workbook.** Decisions, assumptions, issues raised during authoring belong in the draft itself, not as `add_decision` / `add_issue` / `add_assumption` calls.
+6. **No placeholders, no hallucinations.** Every claim in the draft must be grounded in the seed, QA transcript, repo discovery, or PRD content. If you cannot ground a section, it goes into `## Open Questions`.
+
+## State Machine (TRD §5.5.1)
+
+```
+IDLE
+  └─→ DETECT_INTENT (seed gathering)
+        ├─→ SCAN_EXISTING_WORK   (skippable, PRD)
+        ├─→ CLARIFY               (adaptive depth, interruptible)
+        ├─→ PROPOSE_PLACEMENT     (PRD only, skippable)
+        ├─→ CREATE_FEATURE        (PRD only, new features)
+        ├─→ TRD_DISCOVERY         (TRD only)
+        ├─→ MIN_CONTEXT_GATE      (TRD only, non-skippable)
+        ├─→ DRAFT
+        ├─→ ITERATE               (skippable)
+        ├─→ QUALITY_GATE          (TRD only, non-skippable)
+        └─→ FINALIZE
+              └─→ IDLE
+```
+
+**Skip phrases**: `skip`, `draft it`, `just write it`, `next` — case-insensitive, trailing punctuation OK. These short-circuit the current step EXCEPT in `MIN_CONTEXT_GATE` and `QUALITY_GATE`.
+
+**Skill arguments** (`$ARGUMENTS`):
+- positional: feature name or UUID (optional — drives DETECT_INTENT)
+- `--doc prd` | `--doc trd` (defaults: see DETECT_INTENT)
+- `--revise-existing` (TRD only, per TRD §5.5.4)
+
+## Step 0: Read Repo Config
+
+Read `.dezycro/config.json` from the repo root. If missing, tell the user:
+
+> No `.dezycro/config.json` found. Run `/dezycro:init` first to set up this repository.
+
+Stop. Otherwise extract `workspaceId` and `projectId`.
+
+## Step 1: DETECT_INTENT
+
+Parse `$ARGUMENTS`. Three sub-paths:
+
+**(a) Feature provided + `--doc trd`** → TRD flow. Validate PRD is APPROVED (see Step 2 TRD).
+**(b) Feature provided + `--doc prd`** → PRD flow for an existing feature (typically `--revise-existing` style PRD edits). Confirm with user before reopening if PRD is already APPROVED (EC-10).
+**(c) No `--doc` or no feature** → ask the user via `AskUserQuestion`:
+  - "Are we authoring a PRD (new feature concept) or a TRD (technical design for an existing feature)?"
+
+For a **PRD with no feature seed**, prompt the user for a one-paragraph seed describing the problem they want to solve. Store it; you'll feed it into P-2 / P-3 / P-4.
+
+For a **TRD**, resolve the feature ID via `search_features` (mirror `/dezycro:work` Step 2). Call `list_feature_documents(workspaceId, featureId)`:
+- If no PRD or PRD `status != "APPROVED"` → **REFUSE per EC-14**:
+  > Cannot author TRD: no approved PRD exists for this feature. Run `/dezycro:author --doc prd` first.
+- Otherwise capture `prdDocId` and call `get_document(workspaceId, featureId, prdDocId)` to load `prdContent`. Also check if a TRD already exists — if so and `--revise-existing` not passed, ask: "A TRD exists for this feature. Revise it (re-enter authoring) or cancel?"
+
+Once the doc type and (for TRD) the feature are known, **enter authoring mode** by running:
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/hooks/companion-runner authoring-state \
+  --set=enter --doc-id=<docId-or-placeholder> --doc-type=<PRD|TRD> \
+  --feature-id=<featureId-or-empty> --seed=<short-seed-text>
+```
+
+(For PRDs on a brand-new feature, you won't have `docId` yet — use a temporary id like `prd-pending-<ts>` and re-enter once you've created the feature in CREATE_FEATURE.)
+
+This sets `authoringMode=true` so the Stop hook will skip the workbook sweep for this session.
+
+## Step 2: Route by Doc Type
+
+### Step 2A: PRD Flow (TRD §5.5.2)
+
+#### SCAN_EXISTING_WORK (skippable)
+
+Call `search_features(workspaceId, projectId, query=keyTermsFromSeed)`. Take up to the top 10 results.
+
+Read `${CLAUDE_PLUGIN_ROOT}/prompts/existing-work-ranker.md` (this is P-2). Substitute `{{seed_paragraph}}` and `{{search_results_json}}` with the seed and the search-result JSON, then **invoke P-2 in your own context** — produce the strict JSON output the prompt specifies. Show the user the top 3 results with a one-line rationale each.
+
+Ask: "Is your feature an extension of any of these, or genuinely new?" If the user picks an adjacent feature, switch to a revise-PRD flow on that feature. If "new" or skip phrase → continue.
+
+#### CLARIFY (interruptible, adaptive)
+
+Loop:
+1. Read `${CLAUDE_PLUGIN_ROOT}/prompts/prd-question.md` (P-3). Substitute placeholders with the seed, `answered_categories_json` (categories you've already covered), the QA transcript so far, and the adjacent-features JSON.
+2. Invoke P-3 in context to produce the next question (one at a time, JSON-validated).
+3. If `should_stop=true`, exit the loop and continue to PROPOSE_PLACEMENT.
+4. Otherwise ask the user the `next_question`. Use `AskUserQuestion` with the provided `options` when `question_kind == "multiple_choice"`; otherwise open-ended.
+5. Append the answer to `.dezycro/authoring-transcript.json` (under `qaTurns`) so it survives compaction.
+6. If the user's message matches a skip phrase, exit the loop and continue.
+
+#### PROPOSE_PLACEMENT (skippable)
+
+Call `suggest_placement(workspaceId, projectId, seedSummary)`. Show the proposed directory; let the user override or accept. Skip phrase → use the top suggestion.
+
+#### CREATE_FEATURE
+
+Call `create_feature(workspaceId, projectId, name, directoryId)`. Capture the new `featureId` and the auto-created PRD `docId`. **Re-enter authoring** with the now-real `docId`:
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/hooks/companion-runner authoring-state \
+  --set=enter --doc-id=<real-prd-docId> --doc-type=PRD --feature-id=<featureId>
+```
+
+#### DRAFT
+
+Read `${CLAUDE_PLUGIN_ROOT}/prompts/prd-drafter.md` (P-4). Substitute `{{seed}}`, `{{qa_transcript_json}}`, `{{adjacent_features_json}}`, and `{{existing_content_or_null}}`. Invoke P-4 in context to produce the PRD Markdown. Validate it locally (≥500 chars, required section headings present per the P-4 system prompt).
+
+Write the draft to the document:
+
+```
+update_document(workspaceId, featureId, docId, content=<the draft>)
+```
+
+#### ITERATE (skippable)
+
+Accept user edits. For substantive revisions, re-invoke P-4 with the prior draft as `existing_content`. For minor wording, edit directly.
+
+#### FINALIZE
+
+Call `change_document_status(workspaceId, featureId, docId, status=APPROVED)`. **PRD finalize is NOT gated** — the PreToolUse hook lets it through.
+
+Then exit authoring mode:
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/hooks/companion-runner authoring-state --set=exit
+```
+
+Tell the user:
+> PRD `<name>` approved. To author the TRD, run `/dezycro:author <feature-name> --doc trd`.
+
+Command stops here.
+
+### Step 2B: TRD Flow (TRD §5.5.3)
+
+#### TRD_DISCOVERY
+
+Build a structured repo + workbook context bundle:
+
+1. **Stack detection** — read `package.json`, `pom.xml`, `build.gradle.kts`, `requirements.txt`, `go.mod`, etc. Note the language / framework.
+2. **Controller / service / repository structure** — list a couple of representative paths via Glob (e.g., `**/controllers/**`, `**/services/**`, `**/repositories/**`).
+3. **Migrations** — find the migrations dir (Flyway / Liquibase / Alembic / etc.).
+4. **Queue / messaging config** — Kafka, Pub/Sub, NATS, etc. — grep around for clues.
+5. **Auth config** — Spring Security, Zitadel, OAuth, etc.
+6. **Workbook** — call `get_workbook(workspaceId, featureId)`. Capture assumptions, decisions, open issues.
+
+Read `${CLAUDE_PLUGIN_ROOT}/prompts/trd-discovery.md` (P-5). Substitute `{{prd_content}}`, `{{repo_context_json}}` (the bundle you just built), and `{{workbook_json}}`. Invoke P-5 in context to produce `discoverySummary` JSON (strict schema: `confirmed_context`, `likely_conventions`, `missing_context`).
+
+Persist it: append `discoverySummary` to `.dezycro/authoring-transcript.json` (your in-context state machine should also keep it in memory for the rest of the flow).
+
+Show the user a compact summary:
+
+```
+Confirmed (from PRD / workbook): N facts
+Likely conventions (inferred from repo): N facts
+Missing context (needs Q&A): N items across <category list>
+```
+
+#### CLARIFY
+
+Read `${CLAUDE_PLUGIN_ROOT}/prompts/trd-question.md` (P-6). Substitute `{{discovery_summary_json}}`, `{{answered_categories_json}}`, `{{qa_transcript_json}}`. Invoke P-6 in context.
+
+Loop the same way as the PRD CLARIFY step. Crucially: P-6 will NOT stop early until every category in `{DATA_MODEL, API_CONTRACT, STATE_OR_PERSISTENCE, FAILURE_MODES, MIGRATION_OR_ROLLOUT}` has either an answer or evidence in confirmed_context / likely_conventions.
+
+If the user uses a skip phrase mid-loop, exit immediately — but warn them that MIN_CONTEXT_GATE may bounce the draft back.
+
+#### MIN_CONTEXT_GATE (NON-SKIPPABLE)
+
+This gate has two layers:
+
+**Deterministic** — `lib/quality-gate.js:minContextGate` is the canonical implementation. For each of the five required categories (`data_model`, `api_contracts`, `state_or_persistence`, `failure_modes`, `migration_or_rollout`):
+
+- gather entries from `discoverySummary.confirmed_context[category]` ∪ `discoverySummary.likely_conventions[category]` ∪ `qaTurns` whose `category` matches.
+- require ≥ 1 entry AND combined evidence string (whitespace-normalized) is ≥ 80 characters.
+
+If any category fails, return to CLARIFY and surface the missing list. Do not proceed.
+
+**LLM layer (P-7)** — only if deterministic passes. Read `${CLAUDE_PLUGIN_ROOT}/prompts/trd-context-gate.md` (P-7). Substitute `{{discovery_summary_json}}` and `{{qa_transcript_json}}`. Invoke P-7 in context. If `ready=false`, surface the `missing` map and `rationale` to the user, return to CLARIFY.
+
+If both layers pass → proceed to DRAFT.
+
+#### DRAFT
+
+Read `${CLAUDE_PLUGIN_ROOT}/prompts/trd-drafter.md` (P-8). Substitute `{{prd_content}}`, `{{discovery_summary_json}}`, `{{qa_transcript_json}}`, `{{existing_content_or_null}}`. Invoke P-8 in context to produce the TRD Markdown.
+
+**Critical**: per P-8's contract, use the `Confirmed / Recommended Defaults / Open Questions` sub-structure where appropriate. Do NOT promote inferences to confirmed facts.
+
+Write the draft via `update_document(workspaceId, featureId, trdId, content=<draft>)`.
+
+**Then update the draft sidecar** — this is what the PreToolUse:change_document_status hook reads to enforce the deterministic gate belt-and-suspenders. Write the draft to `.dezycro/authoring-current-draft.json` with the shape:
+
+```json
+{
+  "docId": "<trdId>",
+  "docType": "TRD",
+  "content": "<full TRD markdown>",
+  "prdDocId": "<prdDocId>",
+  "prdContent": "<full PRD markdown>",
+  "updatedTs": "<ISO timestamp>"
+}
+```
+
+Refresh this sidecar **every time** the TRD draft changes (DRAFT and any substantive ITERATE revision). The hook gates `change_document_status` against whatever is in the sidecar.
+
+#### ITERATE (skippable)
+
+Accept user edits; re-run P-8 for substantive revisions; refresh the sidecar after each rewrite.
+
+#### QUALITY_GATE (NON-SKIPPABLE)
+
+**Deterministic layer** — `lib/quality-gate.js:deterministicTrdGate` is the canonical implementation. Verify locally before invoking P-9:
+
+- TRD content ≥ 1000 chars (trimmed).
+- Required H2 sections present: `## Architecture`, `## Data Model`, `## API Contracts`, `## Failure Modes` (or `## Failure Modes and Edge ...`), `## Migration` (or `## Migration / Rollout`), `## Open Questions` (heading-case-insensitive).
+- No placeholder tokens: regex `\b(TBD|TODO|FIXME|fill in later|to be determined)\b` (case-insensitive).
+- PRD pillar coverage: parse the PRD's `^## Pillar \d+:\s*(.+)$` headings; each pillar name must appear verbatim in the TRD body.
+
+If any of these fail → return to ITERATE with the blocking issues. Do not invoke P-9.
+
+**P-9 layer** — read `${CLAUDE_PLUGIN_ROOT}/prompts/trd-reviewer.md`. Substitute `{{prd_content}}`, `{{trd_content}}`, `{{discovery_summary_json}}`. Invoke P-9 in context to produce the strict JSON output.
+
+**Code-side enforcement** — per TRD §6.9 / `lib/quality-gate.js:enforceP9Result`, regardless of what `approved` says, the gate REJECTS if any of these are true:
+- `score < 0.85`
+- `suspected_inventions` contains any architecture / data-model / API-contract / migration / auth / queue / verifier-behavior claim (case-insensitive substring match).
+
+On rejection: show `blocking_issues` and `suspected_inventions` to the user, return to ITERATE.
+
+On pass: proceed to FINALIZE.
+
+#### FINALIZE
+
+Call `change_document_status(workspaceId, featureId, trdId, status=APPROVED)`. The PreToolUse hook will re-run the deterministic gate against the sidecar — if anything has drifted since your local check, the hook will block. If that happens, refresh the sidecar and try again.
+
+On success, exit authoring mode:
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/hooks/companion-runner authoring-state --set=exit
+```
+
+Tell the user:
+> TRD `<name>` approved. You can now `/dezycro:work` this feature.
+
+## Cancellation
+
+If the user says "cancel" or "stop authoring" at any point, exit cleanly:
+
+```bash
+${CLAUDE_PLUGIN_ROOT}/hooks/companion-runner authoring-state --set=exit
+```
+
+Do NOT call `change_document_status` on the draft — leave the doc in `DRAFT` for the user to revisit.
+
+## Compaction Survival
+
+If your context is compacted mid-flow, the next `SessionStart` will inject the transcript summary because `authoringMode=true` on disk. On resume:
+1. Re-read `.dezycro/authoring-transcript.json`.
+2. Re-read `.dezycro/authoring-current-draft.json` if it exists (TRD only).
+3. Ask the user where you left off ("It looks like we were drafting the TRD for `<feature>`. Want to keep iterating or restart from CLARIFY?").
+
+## Prompt Reference
+
+Read each prompt file from disk, substitute `{{placeholders}}` with current state (string replacement), and invoke the LLM call **in your own context** — do not shell out to a separate LLM API.
+
+| Step | Prompt file | Section |
+|---|---|---|
+| SCAN_EXISTING_WORK (PRD) | `prompts/existing-work-ranker.md` | TRD §6.2 (P-2) |
+| CLARIFY (PRD) | `prompts/prd-question.md` | TRD §6.3 (P-3) |
+| DRAFT (PRD) | `prompts/prd-drafter.md` | TRD §6.4 (P-4) |
+| TRD_DISCOVERY | `prompts/trd-discovery.md` | TRD §6.5 (P-5) |
+| CLARIFY (TRD) | `prompts/trd-question.md` | TRD §6.6 (P-6) |
+| MIN_CONTEXT_GATE LLM | `prompts/trd-context-gate.md` | TRD §6.7 (P-7) |
+| DRAFT (TRD) | `prompts/trd-drafter.md` | TRD §6.8 (P-8) |
+| QUALITY_GATE LLM | `prompts/trd-reviewer.md` | TRD §6.9 (P-9) |
+
+Each prompt declares its strict JSON output schema (where applicable). If the JSON fails to parse, log it, treat as "no signal" for that step, and ask the user to retry the step.