@dezycro-ai/agent-plugin 2.0.0

package/skills/status/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: status
+description: Show a compact workbook summary for the active feature — journeys, tasks, issues, and latest verification results. Requires an active feature (run /dezycro:work first).
+---
+
+# Dezycro Feature Status
+
+You are displaying a compact workbook summary for the active Dezycro feature.
+
+## Step 1: Read Active Feature
+
+Read `.dezycro/active-feature.json` using the Read tool. If the file does not exist, tell the user:
+
+> No active feature. Run `/dezycro:work <feature-name>` first to select a feature.
+
+Then stop.
+
+Extract `featureId` and `featureName`.
+
+## Step 2: Read Config
+
+Read `.dezycro/config.json` to get `workspaceId`.
+
+## Step 3: Fetch Workbook
+
+Call `get_workbook(workspaceId, featureId)`.
+
+## Step 4: Fetch Coverage Report
+
+Call `get_coverage_report(workspaceId, featureId)`. Treat a `null` `report` (no run yet) as gate-clear and skip the coverage line — otherwise compute:
+- **bound**: `boundButNotExecutable.length + executableButNotObserved.length` (ops bound to a JEP but not yet observed)
+- **inconclusive**: `observedButInconclusive.length`
+- **failed**: `decisiveFailures.length`
+- **scope**: `executionContexts.join(",")` (typically `API`)
+
+## Step 5: Render Summary
+
+From the workbook response, compute:
+- **Journeys**: count by status (PASSING, FAILING, PENDING, SKIPPED) — only count `enforced` journeys for the X/Y ratio
+- **Tasks**: count by status (CONFIRMED, PUSHED, DONE, IN_PROGRESS, PENDING) — show confirmation progress: "X/Y confirmed"
+- **Issues**: count OPEN issues, group by severity
+- **Latest verify**: timestamp of most recent entry in `verifierRuns`, and its pass/total count
+
+Display:
+
+```
+Feature: <featureName> (<lifecycle status>)
+Journeys: X/Y passing, Z failing, W pending
+Tasks:    N total — A confirmed, B pushed, C done, D in progress, E pending
+Issues:   M open (severities)
+Verify:   last run <relative time> — X/Y
+Coverage: A bound · B inconclusive · C failed · scope=<scope>
+```
+
+If the coverage report was null (no run processed yet), drop the `Coverage:` line entirely. If `lifecycleBlocking` is `true`, append ` ⛔ blocks VERIFIED` to the coverage line.
+
+If there are **OPEN HIGH issues**, list each:
+```
+HIGH issues:
+  - <summary>
+```
+
+If there are **FAILING journeys**, list each:
+```
+Failing journeys:
+  JOURNEY-X: <description>
+  JOURNEY-Y: <description>
+```
+
+If there are **IN_PROGRESS tasks**, list each:
+```
+In-progress tasks:
+  - <title>
+```
+
+Keep the output compact. No extra explanations unless the user asks follow-up questions.

package/skills/sync/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: sync
+description: Sync your current work to the Dezycro workbook — creates tasks, records decisions, links commits, and flags issues. Run periodically during development to keep the workbook current.
+---
+
+# Sync Agent Context
+
+You are reviewing what work has been done on the active feature and updating the Dezycro workbook to reflect it.
+
+## Step 1: Read Active Feature
+
+Read `.dezycro/active-feature.json` and `.dezycro/config.json`. If no active feature, tell the user to run `/dezycro:work` first.
+
+## Step 2: Get Current Workbook State
+
+Call `get_workbook(workspaceId, featureId)` to see what's already tracked.
+
+## Step 3: Review Recent Work
+
+Look at what has happened since the feature was loaded:
+
+1. **Git commits**: Run `git log --oneline --since="<selectedAt from active-feature.json>"` to see commits made during this session.
+
+2. **Files changed**: Run `git diff --name-only HEAD~5` (or since the feature was loaded) to understand what areas were touched.
+
+3. **Current conversation context**: Review what you've been working on in this session — decisions made, problems encountered, assumptions relied on.
+
+## Step 4: Update Workbook
+
+For each item identified, use the appropriate MCP tool:
+
+### Tasks
+- For each distinct unit of work completed or in progress, check if a matching task exists in the workbook.
+- If not, call `create_task(workspaceId, featureId, title, journeyRefs, intentRefs, notes)` to create it.
+- If a task exists and its status changed (e.g., you finished implementing it), call `update_task(workspaceId, featureId, taskId, status)`.
+- Link tasks to the required journeys they cover (`journeyRefs`).
+
+### Decisions
+- For any architectural or design decision made during the session, call `add_decision(workspaceId, featureId, summary, reason, journeyRefs)`.
+- Include the rationale — this is the audit trail for why code was written a certain way.
+
+### Issues
+- For any issue that blocked progress or required a workaround, call `add_issue(workspaceId, featureId, summary, severity, intentRefs)`.
+- Use HIGH for things that prevent journey completion, MEDIUM for workarounds, LOW for minor friction.
+
+### Assumptions
+- For any assumption made that hasn't been validated, call `add_assumption(workspaceId, featureId, summary)`.
+
+### Artifacts
+- For meaningful commits, call `link_artifact(workspaceId, featureId, artifactType="COMMIT", ref=<commit SHA>, linkedIds=<task IDs>)`.
+- For PRs, call `link_artifact(workspaceId, featureId, artifactType="PR", ref=<PR URL>)`.
+
+## Step 5: Display Summary
+
+Show what was synced:
+
+```
+Workbook synced for "<featureName>"
+
+  Tasks: X created, Y updated
+  Decisions: N recorded
+  Issues: M flagged
+  Artifacts: P linked
+
+Current state:
+  Journeys: A/B passing
+  Tasks: C done, D in progress, E pending
+```
+
+## Guidelines
+
+- Don't create duplicate tasks — check existing tasks before creating new ones.
+- Be specific in task titles — "Implement login endpoint" not "Work on feature".
+- Always include `journeyRefs` when the work covers a specific required journey.
+- Record decisions even if they seem obvious — the workbook is for humans reviewing later.
+- Don't over-sync — only record meaningful work, not every small edit.

package/skills/verify/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: verify
+description: Pull the latest verifier binary, run it against the local (or remote) environment, and upload results to the workbook. Requires an active feature (run /dezycro:work first). Accepts optional --env argument to select environment.
+---
+
+# Run Dezycro Verification
+
+You are pulling the verifier binary for the active feature, running it against the configured environment, and uploading results.
+
+## Step 0: Check for Pending Spec Publish (Pillar 2)
+
+Before running verify, check whether Companion's controller-edit tracker recorded any controller-path edits since the last spec publish. The PostToolUse hook flips `needsSpecPublish=true` whenever an Edit/Write/MultiEdit touches a file matching `companion.autoVerify.controllerPaths` (TRD §5.2).
+
+Run:
+
+```bash
+companion-runner state --get
+```
+
+(If the binary isn't on PATH, fall back to `node ${CLAUDE_PLUGIN_ROOT}/hooks/companion-runner state --get`.)
+
+Parse the JSON. If `needsSpecPublish === true` AND `controllerEditsSinceLastPublish` is non-empty:
+
+1. Print the announcement verbatim (replacing `<list>` with the paths from `controllerEditsSinceLastPublish[*].path`, comma-separated):
+
+   > Controllers changed since last published spec: \<list\>. Publishing spec before verify.
+
+2. Invoke `/dezycro:publish-spec` programmatically before continuing.
+
+3. Poll the feature's `verifyPending` flag every 5 seconds (call `get_workbook(workspaceId, featureId)` and read the feature record) until it clears or 5 minutes elapse — this matches the verifier compile SLA.
+
+4. After publish-spec returns control, clear the flags so the same edits don't re-trigger on the next verify:
+
+   ```bash
+   companion-runner state --patch='{"needsSpecPublish": false, "controllerEditsSinceLastPublish": []}'
+   ```
+
+   Note the `=` after `--patch` — the argv parser requires the `=` form (space-separated form is reserved for the `--route` flag).
+
+5. Continue to Step 1.
+
+If `needsSpecPublish` is false (or `companion-state.json` is missing), continue to Step 1 immediately. If the `companion-runner` binary isn't installed (Companion V1 repos), skip Step 0 entirely.
+
+## Step 1: Read Active Feature
+
+Read `.dezycro/active-feature.json` using the Read tool. If the file does not exist, tell the user:
+
+> No active feature. Run `/dezycro:work <feature-name>` first to select a feature.
+
+Then stop.
+
+Extract `featureId` and `featureName`.
+
+## Step 2: Read Config
+
+Read `.dezycro/config.json` using the Read tool. Extract `workspaceId` and `environments`.
+
+Parse the command arguments (`$ARGUMENTS`) for `--env <name>`. If provided, use that environment. Otherwise, find the environment with `"default": true`. If no default, use the first environment.
+
+Extract from the selected environment:
+- `setup` (optional) — command to start the environment
+- `apiUrl` (required) — base URL for the verifier
+- `healthCheck` (optional) — command to check if environment is ready
+- `teardown` (optional) — command to stop the environment
+
+## Step 3: Environment Setup
+
+If the selected environment has a `setup` command:
+
+1. Run the setup command via Bash tool.
+2. If there's a `healthCheck` command, poll it:
+   - Run the health check command via Bash.
+   - If it fails (non-zero exit), wait 2 seconds and retry.
+   - Retry up to 15 times (30 seconds total).
+   - If still failing after 15 retries, tell the user:
+     > Environment health check failed after 30 seconds. Check your setup command and health check endpoint.
+     > Setup: `<setup command>`
+     > Health check: `<healthCheck command>`
+   - Then stop.
+
+If no `setup` command, skip this step. If there's a `healthCheck` but no `setup`, still run the health check.
+
+## Step 4: Pull Verifier Binary
+
+1. Detect the platform by running via Bash:
+   ```bash
+   echo "$(uname -s | tr '[:upper:]' '[:lower:]')/$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')"
+   ```
+   This gives you the platform string like `darwin/arm64` or `linux/amd64`.
+
+2. Call `pull_verifier(featureId, platform)` via MCP (using the `pull_verifier` tool with `featureId` and `platform` parameters).
+
+3. If the tool returns an error indicating no binary exists:
+   - Check generation status by calling `generation_status(workspaceId, featureId)` via MCP.
+   - If generation is **in progress** (status is not IDLE/COMPLETE/FAILED):
+     - Tell the user: "JEP generation in progress — waiting for binary..."
+     - Poll `generation_status` every 15 seconds, up to 20 times (5 minutes).
+     - Show a brief status update every poll: "Still generating... (<status>)"
+     - Once status is COMPLETE, retry `pull_verifier`.
+     - If status is FAILED or timeout reached, tell the user:
+       > JEP generation failed or timed out. Check the generation logs or run `/dezycro:publish-spec` to retry.
+     - Then stop.
+   - If generation is **IDLE** (never started):
+     - Tell the user:
+       > No verifier binary available. The feature needs an API spec first.
+       > Run `/dezycro:publish-spec` to upload your spec and trigger JEP generation.
+     - Then stop.
+
+4. From the response, extract `downloadUrl`, `contentHash`, and any CLI usage hints.
+
+5. Check if the binary is already cached:
+   ```bash
+   ls .dezycro/bin/<contentHash>/dezycro-verify 2>/dev/null && echo "cached" || echo "not-cached"
+   ```
+
+6. If not cached, download and cache it:
+   ```bash
+   mkdir -p .dezycro/bin/<contentHash>
+   curl -fSL -o .dezycro/bin/<contentHash>/dezycro-verify "<downloadUrl>"
+   chmod +x .dezycro/bin/<contentHash>/dezycro-verify
+   ```
+
+## Step 5: Load Auth Personas (from `.dezycro/auth.local.json`)
+
+The generated verifier expects each persona's auth config to be present as an environment variable whose name is declared in `.dezycro/auth.local.json` (`personas.<name>.envVar`, e.g. `AUTH_ADMIN1`). Without these, every authenticated request fails and the run looks broken for the wrong reason. Full schema in `PERSONAS.md` in the claude-plugin (`!file:` / `!env:` / `!cmd:` secret backends, `${VAR}` placeholders, auth types: `bearer`/`basic`/`header`/`http_endpoint`/`js`/`none`).
+
+Use `dezycro-resolve-auth` — it reads `.dezycro/auth.local.json`, resolves secrets, substitutes `${…}` placeholders, and emits `export KEY='value'` lines that must be consumed via `eval` (so the shell strips the quotes before the binary sees the value — `env $(…)` does NOT work here and will produce `invalid character '\''` JSON parse errors):
+
+```bash
+eval "$(dezycro-resolve-auth)"
+```
+
+If the binary isn't on PATH (plugin not installed globally), fall back to invoking the script directly from the repo's claude-plugin dir:
+
+```bash
+eval "$(node claude-plugin/bin/resolve-auth.js)"
+```
+
+Do not hand-roll the exports from `.github/workflows/ci.yml` — `auth.local.json` is the source of truth and will drift if you do.
+
+If `.dezycro/auth.local.json` does not exist, the script prints a stderr warning and emits nothing — `eval` of empty input is a no-op, which is the right behavior (dev/prod runs may inject credentials another way, or the user may have already exported them). Per-persona secret failures are stderr warnings only, so a missing `!file:` secret for one persona will NOT block unrelated personas.
+
+## Step 6: Run Verifier
+
+Run the verifier binary via Bash, in the same shell invocation as the `eval` from Step 5 so the exports carry over:
+
+```bash
+eval "$(dezycro-resolve-auth)"
+.dezycro/bin/<contentHash>/dezycro-verify run --all --base-url <apiUrl> --json
+```
+
+Capture the full stdout output. The verifier outputs JSON with path results.
+
+If the binary fails to execute (non-zero exit with no JSON output), show stderr and suggest:
+> Verifier binary failed to execute. Try:
+> - `./dezycro-verify doctor` to check connectivity
+> - Verify your API is running at `<apiUrl>`
+> - Check that the binary matches your platform
+> - Confirm the expected `AUTH_*` env vars from `.dezycro/auth.local.json` are set
+
+## Step 7: Upload Results
+
+Take the JSON output from Step 6 and call `record_verifier_run` via MCP:
+- `workspaceId`: from config
+- `featureId`: from active feature
+- `results`: the full JSON output as a string
+- `specHash`, `flowVersion`, `jepVersion`: extract from the verifier JSON output's metadata section if present, otherwise omit
+
+This automatically updates journey statuses in the workbook and may trigger lifecycle transitions (IN_PROGRESS -> VERIFIED if all enforced journeys pass and all journey-linked tasks are PUSHED).
+
+## Step 8: Display Results
+
+Parse the JSON output and display a summary:
+
+```
+Verification Results: X/Y passed
+
+PASSING:
+  JOURNEY-1: <description>
+  JOURNEY-2: <description>
+
+FAILING:
+  JOURNEY-3: <description>
+    -> <HTTP method> <endpoint> returned <actual status> (expected <expected status>)
+    -> Intent: "<intent reference>"
+
+SKIPPED:
+  JOURNEY-8: <description> (not enforced)
+```
+
+## Step 9: Surface Coverage Gaps
+
+The verifier run also feeds the coverage projection. Call `get_coverage_report(workspaceId, featureId)` once the upload from Step 7 has settled. If the response carries a `null` report, skip this step — the projection materializes asynchronously and may not be ready on the first call.
+
+If the report is present, take the top 3 entries (in this priority order) from `decisiveFailures` first, then `observedButInconclusive` to fill the remaining slots, and surface them with action hints derived from `verdict`:
+
+| Verdict                              | Action hint                                                                          |
+|--------------------------------------|--------------------------------------------------------------------------------------|
+| `FAIL_DECISIVE_ROUTE_MISSING`        | Endpoint not implemented — implement it or remove from the spec                       |
+| `FAIL_DECISIVE_CONTRACT`             | Response shape does not match the spec — fix the endpoint or update the spec         |
+| `FAIL_DECISIVE_PERSISTENCE`          | State did not persist — investigate the write path                                    |
+| `INCONCLUSIVE_AUTH_REQUIRED`         | Supply an auth fixture in `.dezycro/auth.local.json` for the persona that owns it    |
+| `INCONCLUSIVE_SETUP_REQUIRED`        | Required setup state is missing — supply prerequisites (parent resource, fixture)    |
+| `INCONCLUSIVE_INPUT_CONSTRAINT`      | Input did not satisfy a constraint — supply a valid fixture for the parameter         |
+
+Display:
+
+```
+Coverage gaps (top 3):
+  - <operationId> [<verdict>] -> <action hint>
+  - <operationId> [<verdict>] -> <action hint>
+  - <operationId> [<verdict>] -> <action hint>
+```
+
+If the report has zero entries in both buckets, print `Coverage: clear ✓` instead. If `lifecycleBlocking` is `true`, prepend a one-line note: `⛔ Coverage gate blocks VERIFIED until the entries below are addressed.`
+
+## Step 9b: Update Companion State (Pillar 4)
+
+Tell Companion the verify completed and snapshot the coverage counts so the Stop-hook delta and pre-PUSH nudge can compare against the next run (TRD §5.4.1). Extract three counts from the `get_coverage_report` response from Step 9:
+
+- `uncoveredPaths`     — count of paths with no covering journey
+- `endpointsNotInSpec` — count of observed endpoints absent from the spec
+- `staleBaselines`     — count of baselines older than `staleBaselineDays` (default 14)
+
+If the report was null/missing, set all three to 0. Then run:
+
+```bash
+companion-runner state --patch='{"lastVerifyCompletionTs":"<iso-8601-now>","coverageSnapshot":{"uncoveredPaths":<n>,"endpointsNotInSpec":<n>,"staleBaselines":<n>}}'
+```
+
+(Fall back to `node ${CLAUDE_PLUGIN_ROOT}/hooks/companion-runner state --patch=…` if the binary isn't on PATH. Skip the entire step if the binary isn't installed — V1 repos.)
+
+This is a fire-and-forget bookkeeping step. If the patch returns a lock-contention error, do not retry — the next verify will overwrite.
+
+## Step 10: Teardown (Optional)
+
+If the selected environment has a `teardown` command, ask the user:
+
+> Want to tear down the environment? (`<teardown command>`)
+
+If yes, run it via Bash.
+
+## Next Steps
+
+Based on results:
+- **All journeys passing**: "All journeys passing! The feature may auto-transition to VERIFIED."
+- **Some failures**: "Fix the failing journeys and run `/dezycro:verify` again. Focus on: <list top 2-3 failing journeys>."
+- **No journeys passing**: "No journeys passing yet. Review the failing assertions and start implementing the feature endpoints."

package/skills/work/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: work
+description: Start or resume working on a Dezycro feature — gates on PRD/TRD/graph approval, interactively helps pick a feature when none is given, and binds the session to the workbook as the source of truth. Use when starting a coding session. Accepts an optional feature name or UUID as argument.
+---
+
+# Start/Resume Feature Work
+
+You are loading a Dezycro feature's full context so the developer can start (or resume) working on it. **The workbook is the source of truth** — local files (`.dezycro/active-feature.json`) are only a session pointer; every meaningful state change goes through MCP workbook tools.
+
+## Hard Rules — Read Before Anything Else
+
+1. **No approved graph → no work.** A feature with `lifecycleStatus == "DRAFT"` has no approved flow graph, which means no journeys, no JEP, no agent context. **Refuse to start a coding session on it.** Walk the user to the webapp to approve the graph instead. (Lifecycle: `DRAFT` → `APPROVED` happens automatically when the flow graph is approved.)
+2. **No PRD or TRD → no work.** Even if the feature is `APPROVED`, both PRD and TRD documents must exist and be at `status == "COMPLETE"`. Without finalized docs, the agent context is incomplete and you will hallucinate.
+3. **Workbook is canonical.** Every issue you find, every decision you make, every task you complete during this session is persisted to the workbook via MCP tools (`add_issue`, `add_decision`, `add_assumption`, `update_task`, `update_issue`). **Do not** keep findings in scratch files or "I'll remember it" memory — it does not survive the session and the PM cannot see it.
+4. **Lifecycle states allowed for coding:** `APPROVED`, `IN_PROGRESS`, `VERIFIED`. Refuse: `DRAFT`, `SHIPPED`, `ABANDONED` (offer to reopen with the user's confirmation for `ABANDONED`/`SHIPPED`, but do not just dive in).
+
+## Step 1: Read Config
+
+Read `.dezycro/config.json` from the repository root using the Read tool. If the file does not exist, tell the user:
+
+> No `.dezycro/config.json` found. Run `/dezycro:init` first to set up this repository.
+
+Then stop.
+
+Extract `workspaceId` and `projectId` from the config.
+
+## Step 2: Resolve Feature
+
+The user may provide a feature name or UUID as the command argument: `$ARGUMENTS`
+
+### 2a. If `$ARGUMENTS` is a UUID
+
+(Matches pattern `[0-9a-f]{8}-[0-9a-f]{4}-...`.) Use it directly as `featureId`. You will need to fetch its full record later to read `lifecycleStatus`, `name`, and `breadcrumb` — do that by calling `search_features(workspaceId, projectId, query=<the UUID's first 8 chars>)` and matching by `id`, OR by skipping ahead to the lifecycle check via `get_workbook` and `list_feature_documents` and accepting that you'll surface the name from those.
+
+### 2b. If `$ARGUMENTS` is a non-empty string (feature name / substring)
+
+Call `search_features(workspaceId, projectId, query=$ARGUMENTS)`.
+
+- **Exactly one match**: use it.
+- **Multiple matches**: use `AskUserQuestion` with up to 4 options. Label each `<featureName> — <breadcrumb path> · <lifecycleStatus>`. If more than 4 matches, show the 4 most recently updated and add a 5th catch-all "None of these — refine the search" option that re-prompts for a new query.
+- **No matches**: tell the user "No features matched `<query>`. Run `/dezycro:work` with no argument to browse." Then stop.
+
+### 2c. If `$ARGUMENTS` is empty — interactive picker
+
+This is the path most demos and resumed sessions hit. **Do not** dump a flat list of every feature — that's noisy. Help the user navigate.
+
+1. **Call `list_features(workspaceId, projectId)`** (omit `parentDirectoryId` to get the project root). The response has:
+   - `directories[]` with `id`, `name`, `namePath`, `updateTimestamp`
+   - `features[]` with `id`, `name`, `lifecycleStatus`, `updateTimestamp`, `breadcrumb`, `documentSummaries`
+
+2. **Sort `directories[]` by `updateTimestamp` descending** and take the top 5.
+
+3. **Sort root-level `features[]` by `updateTimestamp` descending** and take the top 3 — these are likely active work too.
+
+4. **Use `AskUserQuestion`** with a single question titled "Where do you want to work?" and options built from the sorted lists. Aim for ≤4 options total (the tool's max). Prioritize in this order:
+   - The 2 most recently updated directories (label: `📁 <namePath> — updated <relative time>`)
+   - The most recently updated root-level feature, if any (label: `📄 <name> · <lifecycleStatus>`)
+   - One "🔍 Search by name" option (description: "Type a feature name to search across the whole project")
+   - Always include "📂 Browse from root" as a fallback if you have to drop options to stay ≤4
+
+   The user can always pick "Other" to type a custom answer (e.g., a path like `Backend/Auth/Login` or a folder name).
+
+5. **Handle the response:**
+   - **Folder option** → call `list_features(workspaceId, projectId, parentDirectoryId=<folder.id>)`. Show its directories + features the same way (recently updated first). Recurse until the user picks a feature. Always include a "⬅ Go back" option once you're below the root.
+   - **Root feature option** → use that feature directly.
+   - **Search option** → ask the user for a query, then call `search_features` and resume at 2b.
+   - **"Other" / custom text** → treat as a search query (run `search_features`).
+
+Store the resolved `featureId`, `featureName`, and `lifecycleStatus`.
+
+## Step 3: Lifecycle Gate (HARD STOP if ungated)
+
+You now have a candidate feature. **Before loading anything else**, validate it's workable:
+
+1. If you don't yet have `lifecycleStatus` (e.g. user passed a raw UUID), call `get_workbook(workspaceId, featureId)` and read the feature's status via the parent lookup, OR call `search_features` with a fragment to recover it. The cheapest path: just call `list_feature_documents(workspaceId, featureId)` and `get_workbook(...)` next — both return enough metadata to fail-fast.
+
+2. **Check `lifecycleStatus`:**
+   - `DRAFT` → **REFUSE**. Print:
+     > ⛔ Feature **<name>** is in `DRAFT` — the flow graph hasn't been approved yet, so there's no agent context, no journeys, and no JEP. I won't start a coding session on it.
+     >
+     > **What to do:** open the feature in the webapp, review the flow graph, and approve it. Once approved, the workbook initializes automatically and `/dezycro:work` will load it.
+     
+     Then stop. Do NOT write `.dezycro/active-feature.json`.
+   - `SHIPPED` → **REFUSE**. Print:
+     > ⛔ Feature **<name>** is `SHIPPED`. There's nothing to do here. If you need to extend it, create a new feature or ask the PM to reopen this one.
+     
+     Then stop.
+   - `ABANDONED` → **REFUSE by default**. Print:
+     > ⛔ Feature **<name>** is `ABANDONED`. If this was a mistake, reopen it in the webapp first. I won't start a coding session on an abandoned feature without that step.
+     
+     Then stop.
+   - `APPROVED`, `IN_PROGRESS`, `VERIFIED` → continue to step 4.
+
+3. **Check documents** — call `list_feature_documents(workspaceId, featureId)`. You need:
+   - At least one document with `type == "PRD"` and `status == "COMPLETE"`.
+   - At least one document with `type == "TRD"` and `status == "COMPLETE"`.
+   
+   If either is missing or still `DRAFT` / `IN_PROGRESS`, **REFUSE**:
+   > ⛔ Feature **<name>** is `<lifecycleStatus>` but its documents aren't finalized:
+   > - PRD: <status or "missing">
+   > - TRD: <status or "missing">
+   >
+   > Without a finalized PRD and TRD, the agent context is incomplete and I will hallucinate. Finish the docs in the webapp first.
+   
+   Then stop. Do NOT write `.dezycro/active-feature.json`.
+
+## Step 4: Load Workbook
+
+Call `get_workbook(workspaceId, featureId)`.
+
+From the response, extract:
+- `status` — the workbook/feature lifecycle status (NOT_STARTED / ACTIVE / COMPLETE)
+- `journeys` — list with `journeyId`, `description`, `status` (PENDING/PASSING/FAILING/SKIPPED), `enforced`
+- `tasks` — list with `id`, `title`, `status` (PENDING/IN_PROGRESS/DONE/PUSHED/CONFIRMED)
+- `issues` — list with `summary`, `severity`, `status` (OPEN/RESOLVED/PUSHED/CLOSED)
+- `verifierRuns` — list, take the most recent one for timestamp and results
+
+## Step 5: Load Documents
+
+Call `list_feature_documents(workspaceId, featureId)` to get document IDs (you already have the list from Step 3 — reuse it).
+
+For each finalized document (PRD and TRD):
+- Call `get_document(workspaceId, featureId, docId)`.
+- Note the word count of the content.
+
+Read both the PRD and TRD content — you will need this context to help the developer.
+
+## Step 6: Write Active Feature (session pointer only)
+
+Write `.dezycro/active-feature.json` using the Write tool:
+
+```json
+{
+  "featureId": "<resolved featureId>",
+  "featureName": "<resolved featureName>",
+  "selectedAt": "<current ISO 8601 timestamp>"
+}
+```
+
+Create the `.dezycro/` directory first if it doesn't exist: `mkdir -p .dezycro`
+
+**This file is a pointer, not state.** It tells `/dezycro:status` and `/dezycro:verify` which feature is active. Any actual work — tasks, issues, decisions — lives in the workbook.
+
+## Step 7: Display Summary
+
+Present the feature context to the user in this format:
+
+```
+Feature: <featureName> (<lifecycleStatus>)
+Path:    <breadcrumb joined with " / ">
+
+Journeys: X/Y passing, Z failing, W pending
+Tasks:    N total — A confirmed, B pushed, C done, D in progress, E pending
+Issues:   M open (list severities)
+Verify:   <timestamp or "never"> — X/Y journeys
+
+PRD loaded (N words) | TRD loaded (M words)
+```
+
+If there are **failing journeys**, list them:
+```
+Failing journeys:
+  JOURNEY-X: <description> — FAILING
+  JOURNEY-Y: <description> — FAILING
+```
+
+If there are **open HIGH issues**, list them:
+```
+Open HIGH issues:
+  - <summary>
+```
+
+If there are **in-progress tasks**, list them:
+```
+In-progress tasks:
+  - <title>
+```
+
+## Step 8: Operating Rules (Show Once, Then Enforce)
+
+After the summary, print this reminder verbatim so the developer sees what the agent will and won't do during the session:
+
+> **Workbook is the source of truth for this session.**
+> - I will record every issue I find via `add_issue` — not in chat-only or scratch files.
+> - I will record every decision (e.g. "we chose JWT over session cookies") via `add_decision`.
+> - I will record assumptions I'm making (e.g. "assuming all timestamps are UTC") via `add_assumption`.
+> - I will update task status via `update_task` as I complete work — not local checkboxes.
+> - When you tell me an issue is fixed, I will call `update_issue` to mark it RESOLVED.
+> - Before declaring a journey done, I will run `/dezycro:verify` and let the verifier confirm.
+>
+> If you want me to skip the workbook for something quick (e.g. a one-off question), say so explicitly. Otherwise I will default to writing through.
+
+## Ready
+
+The developer now has full context. Offer:
+
+> Ready to work on "<featureName>". What would you like to do?
+> - Pick a failing journey or open issue to tackle
+> - Start implementing an in-progress task
+> - Run `/dezycro:verify` to test current state
+> - Run `/dezycro:status` for a quick status check