codeforge-dev 1.7.0 → 1.8.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/AGENT-REDIRECTION.md

@@ -0,0 +1,226 @@
+# Agent Redirection Guide
+
+How Claude Code's hook system lets you replace, reroute, or transform any tool call — including swapping built-in subagents for custom ones.
+
+## How It Works
+
+Claude Code plugins can register **PreToolUse hooks** that intercept tool calls before they execute. The hook receives the full tool input as JSON on stdin and can return modified input on stdout. This is the mechanism behind agent redirection: when Claude spawns a subagent via the `Task` tool, a hook intercepts the call and rewrites `subagent_type` to point at a custom agent definition.
+
+### The Hook Contract
+
+```
+stdin  → { "tool_name": "Task", "tool_input": { "subagent_type": "Explore", "prompt": "...", ... } }
+stdout ← { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow", "updatedInput": { ...modified tool_input... } } }
+```
+
+The hook script receives the tool call context on stdin, and can return:
+
+| Field | Effect |
+|-------|--------|
+| `permissionDecision: "allow"` | Let the call proceed (with optional modifications) |
+| `permissionDecision: "deny"` | Block the call entirely (with a reason) |
+| `updatedInput: {...}` | Replace the tool input — Claude Code uses the new values instead of the originals |
+
+**Critical detail**: `updatedInput` **replaces** the original input (it does not merge). Always spread the original fields and override only what you need:
+
+```python
+updated = {**tool_input, "subagent_type": "my-custom-agent"}
+```
+
+### Hook Registration
+
+In your plugin's `hooks/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [{
+          "type": "command",
+          "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/my-hook.py",
+          "timeout": 5
+        }]
+      }
+    ]
+  }
+}
+```
+
+The `matcher` field controls which tool triggers the hook. Use `"Task"` to intercept subagent spawning, `"Bash"` for command execution, `"Edit|Write"` for file modifications, etc.
+
+## What We Do: Built-in → Custom Agent Swap
+
+The `redirect-builtin-agents.py` hook maps Claude Code's built-in agent types to our custom agents:
+
+```python
+REDIRECT_MAP = {
+    "Explore": "explorer",        # Fast codebase search
+    "Plan": "architect",          # Implementation planning
+    "general-purpose": "generalist",  # Multi-step tasks
+    "Bash": "bash-exec",          # Command execution
+    "claude-code-guide": "claude-guide",
+    "statusline-setup": "statusline-config",
+}
+```
+
+When Claude decides to spawn an `Explore` agent, the hook rewrites it to `code-directive:explorer` — a custom agent with tailored instructions, tool restrictions, and model selection. The original prompt passes through unchanged.
+
+### Custom Agent Definitions
+
+Agents are Markdown files with YAML frontmatter in the `agents/` directory:
+
+```yaml
+---
+name: explorer
+description: >-
+  Fast codebase search. Use when you need to find files,
+  search code, or answer structural questions.
+tools: Read, Glob, Grep, Bash        # Restrict available tools
+model: sonnet                         # Or: opus, haiku, inherit
+color: cyan
+memory:
+  scope: project                      # Or: user, global
+skills:
+  - debugging                         # Inject skill knowledge
+---
+
+# Explorer Agent
+
+You are a codebase navigation specialist...
+```
+
+Key frontmatter fields:
+
+| Field | What it controls |
+|-------|-----------------|
+| `tools` | Which tools the agent can use (`"*"` for all, or comma-separated list) |
+| `model` | Which model runs the agent (`sonnet`, `opus`, `haiku`, `inherit`) |
+| `skills` | Skills injected into the agent's context |
+| `memory.scope` | Memory persistence level |
+
+The Markdown body below the frontmatter becomes the agent's system prompt.
+
+## What Else You Can Do
+
+The same hook mechanism supports far more than agent swapping. Here are patterns that work today:
+
+### Modify the Prompt
+
+Inject additional context, constraints, or instructions into any subagent's prompt:
+
+```python
+updated = {
+    **tool_input,
+    "prompt": tool_input["prompt"] + "\n\nALWAYS check for security issues.",
+}
+```
+
+### Change the Model
+
+Force a specific model for certain agent types or tasks:
+
+```python
+if "security" in tool_input.get("prompt", "").lower():
+    updated = {**tool_input, "model": "opus"}  # Use strongest model for security tasks
+```
+
+### Conditional Routing
+
+Route to different agents based on prompt content, file patterns, or environment:
+
+```python
+prompt = tool_input.get("prompt", "")
+if "test" in prompt.lower():
+    target = "test-writer"
+elif "refactor" in prompt.lower():
+    target = "refactorer"
+else:
+    target = "generalist"
+updated = {**tool_input, "subagent_type": f"code-directive:{target}"}
+```
+
+### Block Certain Operations
+
+Deny tool calls that match dangerous patterns:
+
+```python
+# This is exactly how dangerous-command-blocker works for Bash
+response = {
+    "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "deny",
+        "permissionDecisionReason": "This operation is not allowed.",
+    }
+}
+```
+
+### Intercept Any Tool (Not Just Task)
+
+Hooks aren't limited to subagent spawning. You can intercept `Bash`, `Edit`, `Write`, `WebFetch` — any tool:
+
+```json
+{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "python3 my-script.py" }] }
+```
+
+The `dangerous-command-blocker` plugin uses this to inspect Bash commands before execution. The `protected-files-guard` does the same for Edit/Write to block modifications to sensitive files.
+
+### Chain with External Services
+
+Since hooks are just scripts that read stdin and write stdout, you can call anything:
+
+```python
+# Forward the prompt to an external API for analysis
+import requests
+result = requests.post("https://my-api.example.com/analyze", json=tool_input)
+# Use the response to modify the tool call
+```
+
+This opens up patterns like:
+- **External LLM routing** — send the prompt to a classifier that picks the best model/agent
+- **Audit logging** — POST every tool call to an external logging service
+- **Cost control** — check a budget API before allowing expensive operations
+- **RAG injection** — query a vector DB and inject relevant context into the prompt
+
+### PostToolUse: React After Execution
+
+`PostToolUse` hooks run after a tool completes and can inject context back to Claude:
+
+```python
+# Return diagnostic information that Claude will see
+print(json.dumps({"additionalContext": "Lint warning: unused import on line 12"}))
+```
+
+This is how the auto-linter and syntax validator work — they inspect the result of Edit/Write operations and feed findings back into the conversation.
+
+## File Layout
+
+```
+code-directive/
+├── agents/                    # Agent definitions (17 .md files)
+│   ├── explorer.md
+│   ├── architect.md
+│   ├── generalist.md
+│   └── ...
+├── hooks/
+│   └── hooks.json             # Hook registrations
+├── scripts/
+│   ├── redirect-builtin-agents.py   # The redirection hook
+│   ├── collect-edited-files.py      # Collects paths for Stop hooks
+│   ├── syntax-validator.py          # PostToolUse syntax checks
+│   └── skill-suggester.py           # Suggests skills on prompt
+└── skills/                    # Skill definitions (16 directories)
+    ├── fastapi/
+    ├── svelte5/
+    └── ...
+```
+
+## Writing Your Own
+
+1. **Create the agent** — add a `.md` file to `agents/` with YAML frontmatter
+2. **Add the redirect** — add an entry to `REDIRECT_MAP` in `redirect-builtin-agents.py`, or write a new hook script
+3. **Register the hook** — add it to `hooks/hooks.json` under the appropriate event type
+4. **Test** — spawn the agent via Claude and check `/tmp/agent-redirect.log` for redirect entries
+
+The hook always exits 0. If it crashes or times out, Claude Code falls back to the original tool call — so a broken hook never blocks work.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/architect.md

@@ -13,6 +13,8 @@ model: opus
 color: magenta
 memory:
   scope: project
+skills:
+  - api-design
 hooks:
   PreToolUse:
     - matcher: Bash
@@ -89,6 +91,16 @@ Based on your exploration:
 6. **Flag performance-sensitive paths** — Even for non-performance requests, surface changes that touch hot paths, introduce N+1 queries, add blocking I/O, or change algorithmic complexity. Note measurement strategy if relevant.
 7. **Assess risks** — What could go wrong? What are the edge cases? What dependencies could break?
 8. **Define verification** — How will we know each step worked?
+9. **Specify documentation outputs** — Identify which docs this work should produce
+   or update. Distinguish:
+   - **Roadmap entry**: one-line description of what the version delivers (no
+     implementation detail — that belongs in specs)
+   - **Feature spec**: ≤200 line file following the standard template (Version,
+     Status, Intent, Acceptance Criteria, Key Files, Schema, API, Dependencies)
+   - **As-built update**: if modifying an existing feature, identify which spec
+     to update post-implementation
+   Plans that mix roadmap-level and spec-level detail produce artifacts too
+   detailed for strategy and too shallow for implementation.
 
 ### Phase 4: Structure the Plan
 
@@ -150,6 +162,11 @@ List the 3-7 files most critical for implementing this plan:
 - `/path/to/models.py` — Brief reason (e.g., "Data model to extend")
 - `/path/to/test_file.py` — Brief reason (e.g., "Test patterns to follow")
 
+### Documentation Outputs
+- New spec: `.specs/vX.Y.0/feature-name.md` (≤200 lines)
+- Updated spec: `.specs/vX.Y.0/existing-feature.md` — changes: [list]
+- Roadmap update: `.specs/roadmap.md` — add `[ ] feature` to vX.Y.0
+
 ### Risks & Mitigations
 
 | Risk | Likelihood | Impact | Mitigation |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/bash-exec.md

@@ -29,10 +29,10 @@ You are a **command execution specialist** for terminal operations. You run bash
 - **NEVER** amend commits unless the caller explicitly says "amend." Always create new commits by default — amending the previous commit risks destroying work, especially after a pre-commit hook failure.
 - **NEVER** update git config (`git config user.name`, `git config user.email`, etc.).
 - **NEVER** run commands that could expose secrets or credentials to stdout without redaction.
-- **NEVER** run `rm -rf /` or any command that deletes system directories. Block recursive deletion outside of `/workspaces/`.
+- **NEVER** run `rm -rf /` or any command that deletes system directories. Block recursive deletion outside of the workspace root.
 - **NEVER** run commands that risk runaway execution: `while true` loops without exit conditions, fork bombs (`: | : &`), commands that generate unbounded output (`yes`, `cat /dev/urandom`), or commands likely to fill disk (`dd if=/dev/zero`).
 - Always **quote file paths** that contain spaces with double quotes.
-- Prefer **absolute paths** within `/workspaces/` to avoid working directory confusion.
+- Prefer **absolute paths** within the workspace root to avoid working directory confusion.
 
 ## Git Safety Protocols
 
@@ -117,7 +117,7 @@ When a command is complex (piped chains, obscure flags) or potentially destructi
 ```
 # Example: explain before running
 "This will find all .log files older than 7 days and delete them:"
-find /workspaces/project/logs -name "*.log" -mtime +7 -delete
+find ./logs -name "*.log" -mtime +7 -delete
 ```
 For straightforward commands (`git status`, `ls`, `npm test`), execute directly without preamble.
 
@@ -142,7 +142,7 @@ When a command fails, suggest the most likely recovery based on the error patter
 | Permission denied | Check file ownership (`ls -la`), suggest `chmod` or ownership fix |
 | Module/package not found | Suggest `pip install`, `npm install`, or check virtual environment activation |
 | Merge conflict markers | List conflicted files (`git diff --name-only --diff-filter=U`), suggest resolution |
-| `ENOSPC` / disk full | Run `df -h` and `du -sh /workspaces/*` to identify space usage |
+| `ENOSPC` / disk full | Run `df -h` and `du -sh` on workspace directories to identify space usage |
 | Git divergence | Suggest `git pull --rebase` or `git fetch && git log HEAD..origin/<branch>` |
 | Docker daemon not running | Suggest `docker info` to diagnose, check if service needs starting |
 

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/claude-guide.md

@@ -15,6 +15,9 @@ model: haiku
 color: cyan
 memory:
   scope: user
+skills:
+  - claude-code-headless
+  - claude-agent-sdk
 ---
 
 # Claude Guide Agent
@@ -60,32 +63,20 @@ Direct model interaction via the Claude API (formerly Anthropic API). Covers Mes
 ### Local Context Locations
 
 ```
-# Project-level configuration
-/workspaces/.claude/settings.json        # Active settings
-/workspaces/.claude/keybindings.json     # Active keybindings
-/workspaces/.claude/system-prompt.md     # Active system prompt
-/workspaces/CLAUDE.md                    # Project instructions
+# Project-level configuration (relative to workspace root)
+.claude/settings.json        # Active settings
+.claude/keybindings.json     # Active keybindings
+.claude/system-prompt.md     # Active system prompt
+CLAUDE.md                    # Project instructions
 
 # DevContainer configuration
-/workspaces/.devcontainer/config/settings.json          # Default settings
-/workspaces/.devcontainer/config/main-system-prompt.md   # Default system prompt
+.devcontainer/config/defaults/settings.json          # Default settings
+.devcontainer/config/defaults/main-system-prompt.md   # Default system prompt
 
 # Plugin directory
-/workspaces/.devcontainer/plugins/devs-marketplace/plugins/  # All plugins
+.devcontainer/plugins/devs-marketplace/plugins/  # All plugins
 ```
 
-### Claude-Research Reference Library
-
-The workspace includes a claude-research project at `/workspaces/claude-research/` containing:
-- Built-in agent definitions: `/workspaces/claude-research/built-in-agents/v2.1.27/`
-- Feature flags documentation: `/workspaces/claude-research/misc/claude-code-feature-flags-definitive-guide.md`
-- Environment variables: `/workspaces/claude-research/misc/claude-code-env-vars-2.1.33.md`
-- CLI flags reference: `/workspaces/claude-research/misc/claude-code-cli-flags-reference.md`
-- Memory system analysis: `/workspaces/claude-research/misc/claude-code-memory-system-2.1.33.md`
-- SDK documentation: `/workspaces/claude-research/sdk-typescript/` and `/workspaces/claude-research/sdk-python/`
-
-Use these as supplementary references when official docs are insufficient or when answering questions about internals.
-
 ## Behavioral Rules
 
 - **How-to question** (e.g., "How do I add a hook?"): Fetch the relevant docs page, provide the configuration format with a concrete example, and reference any related features.
@@ -147,9 +138,9 @@ If the question involves configuration or SDK usage, provide a complete, runnabl
 **User prompt**: "What environment variables does Claude Code support?"
 
 **Agent approach**:
-1. Read `/workspaces/claude-research/misc/claude-code-env-vars-2.1.33.md` for comprehensive reference
-2. Read local `.devcontainer/config/settings.json` to show which are currently configured
+1. WebFetch the Claude Code documentation for environment variable reference
+2. Read local `.devcontainer/config/defaults/settings.json` to show which are currently configured
 3. Summarize the most important variables with their effects
 
-**Output includes**: Answer with a categorized list of environment variables (model selection, behavior, performance, experimental features), Documentation References to both the local research file and official docs, Related Features noting the `settings.json` `env` field as an alternative to shell environment variables.
+**Output includes**: Answer with a categorized list of environment variables (model selection, behavior, performance, experimental features), Documentation References to the official docs, Related Features noting the `settings.json` `env` field as an alternative to shell environment variables.
 </example>

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/debug-logs.md

@@ -7,6 +7,8 @@ description: >-
 tools: Bash, Read, Glob, Grep
 model: sonnet
 color: red
+skills:
+  - debugging
 ---
 
 # Debug Logs Agent

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/dependency-analyst.md

@@ -14,6 +14,8 @@ model: haiku
 color: blue
 memory:
   scope: project
+skills:
+  - dependency-management
 hooks:
   PreToolUse:
     - matcher: Bash

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/doc-writer.md

@@ -13,6 +13,8 @@ model: opus
 color: cyan
 memory:
   scope: project
+skills:
+  - documentation-patterns
 ---
 
 # Doc Writer Agent
@@ -26,6 +28,9 @@ You are a **senior technical writer** specializing in software documentation, AP
 - **NEVER** add error handling, validation, logging, or any functional code — if you notice missing error handling, mention it in your report rather than adding it.
 - **NEVER** guess behavior. If you cannot determine what code does by reading it, say so explicitly in the documentation with a `TODO: verify` annotation rather than documenting assumed behavior, because incorrect documentation is worse than missing documentation.
 - **NEVER** document private/internal implementation details in public-facing docs (README, API docs). Reserve implementation notes for inline comments or architecture docs targeted at maintainers.
+- **NEVER** reproduce source code, SQL schemas, or type definitions in documentation
+  files. Reference file paths instead — write "see `src/engine/db/connection.py`"
+  not the full function body. The code is the source of truth; copied snippets rot.
 - You may only write or edit: markdown documentation files (`.md`), docstrings inside source files, JSDoc/TSDoc comments, `///` doc comments, and inline code comments. The executable code itself must remain unchanged.
 
 ## Documentation Strategy
@@ -70,6 +75,10 @@ For large codebases, focus on the public API surface rather than trying to docum
 
 Produce documentation that serves the target audience. Different doc types have different readers.
 
+**Sizing rule:** Documentation files consumed by AI (CLAUDE.md, specs, architecture docs)
+should be ≤200 lines each. Split large documents by concern. Each file should be
+independently useful without requiring other docs in the same context window.
+
 ## Documentation Types
 
 ### README Files
@@ -173,6 +182,10 @@ Follow these principles in all documentation:
 - **Architecture docs requested**: Trace the system's component boundaries, data flows, and key decisions. Produce a document that would onboard a new developer effectively.
 - **No specific request**: Ask the user what documentation they need. If they point to a file or module, offer to add inline documentation to its public API.
 - **Behavior unclear**: If you read a function and cannot determine its exact behavior, document what you can verify and add a `TODO: verify — [specific question]` annotation so a human can fill in the gap.
+- **Version ships** (e.g., "consolidate v0.1.0 docs"): Read all build-time artifacts
+  for the version (architecture docs, decision records, phase plans). Consolidate
+  into a single as-built spec. Delete or merge superseded planning artifacts —
+  don't accumulate snapshot documents. Update the relevant spec in place.
 - **Always report** what was documented, what was verified versus assumed, and what needs human review.
 
 ## Output Format

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/explorer.md

@@ -14,6 +14,8 @@ model: haiku
 color: blue
 memory:
   scope: project
+skills:
+  - ast-grep-patterns
 hooks:
   PreToolUse:
     - matcher: Bash

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/generalist.md

@@ -76,7 +76,12 @@ Surface assumptions early. If the task has incomplete requirements, state what y
    - *Medium risk* (function logic, new endpoint): run related unit tests
    - *High risk* (data model, public API, shared utility): run full test suite, check for import/usage breakage
    - If no automated verification is available, state what manual checks the caller should perform.
-6. **Report** — Summarize what was changed, which files were modified, and how to verify.
+6. **Flag spec status** — Check if a feature spec exists for the area you changed
+   (Glob `.specs/**/*.md`, Grep for the feature name). If a spec exists and
+   your changes affect its acceptance criteria or documented behavior, note in your
+   report: which spec, what changed, and whether it needs an as-built update. The
+   orchestrator handles spec updates — do not modify spec files yourself.
+7. **Report** — Summarize what was changed, which files were modified, and how to verify.
 
 ### For Multi-Step Tasks
 
@@ -95,6 +100,10 @@ Surface assumptions early. If the task has incomplete requirements, state what y
 - **Failure or uncertainty**: Report what happened, what you tried, and what the caller could do next. Do not silently skip steps. For partial completion, explicitly list which steps succeeded and which remain.
 - **Silent failure risk** (build passes but behavior may be wrong): When the change affects runtime behavior that automated tests don't cover, note this gap and suggest how the caller can manually verify correctness.
 - **Tests exist for the area being changed**: Run them after your changes. Report results.
+- **Feature implementation complete**: Check `.specs/` for a related spec.
+  If found, include in your report whether acceptance criteria were met and whether
+  the spec needs an as-built update. Stale specs that say "planned" after code ships
+  cause the next AI session to re-plan already-done work.
 
 ## Output Format
 

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/migrator.md

@@ -14,6 +14,8 @@ model: opus
 color: magenta
 memory:
   scope: user
+skills:
+  - migration-patterns
 ---
 
 # Migrator Agent
@@ -113,6 +115,10 @@ Every migration plan should include rollback instructions:
 - **Unknown migration path**: Use WebFetch to research the migration. If no official guide exists, analyze both APIs by reading their documentation and build a mapping. Present the mapping for user review before proceeding.
 - **Migration guide not found**: If WebFetch cannot find an official migration guide, report this explicitly. Offer to analyze the changelog or source code differences between versions instead.
 - If you encounter a breaking change with no clear replacement, stop and report it — do not guess at the correct migration pattern.
+- **Spec awareness**: After migration, check if the migrated files/APIs are referenced
+  in any spec (`Grep` for the file path or API pattern in `.specs/`). If paths,
+  imports, or API signatures changed, list the affected specs in your report so the
+  orchestrator can update them.
 - **Always report** the current step, what was changed, verification results, and what comes next.
 
 ## Output Format

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/refactorer.md

@@ -139,6 +139,10 @@ If the code you need to refactor has no test coverage:
 - **Ambiguous request** (e.g., "Improve this"): Read the code, identify the most impactful smell, and propose a specific transformation. Confirm with the user before proceeding.
 - **Tests fail on baseline**: Stop immediately. Report the failing tests. Do not attempt to refactor against a red baseline — the safety mechanism is broken.
 - If you cannot determine whether a piece of code is truly unused (dynamic dispatch, reflection, or plugin systems make this ambiguous), report it as "potentially unused — manual verification recommended" rather than deleting it.
+- **Spec awareness**: After refactoring, check if the changed files are referenced
+  in any spec (`Grep` for the file path in `.specs/`). If file paths changed
+  (renames, extractions), note the stale references in your report so the
+  orchestrator can update the spec's Key Files section.
 - **Always report** what smells were found, what transformations were applied, and the before/after metrics.
 
 ## Output Format

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/spec-writer.md

@@ -29,6 +29,13 @@ You are a **senior requirements engineer** specializing in structured technical
 - **NEVER** make assumptions about behavior without checking the codebase. Use `Read`, `Glob`, and `Grep` to understand the current system before specifying changes.
 - **NEVER** write vague requirements like "the system should be fast" or "the UI should be user-friendly." Every requirement must be specific, measurable, and testable.
 - **NEVER** combine multiple independent requirements into a single statement. One requirement per line — this makes requirements individually testable and trackable.
+- **NEVER** produce a specification exceeding 200 lines. If a feature requires
+  more, split it into independently loadable sub-specs (one per sub-feature)
+  with a parent overview file that links them. Monolithic specs rot faster
+  than they're consumed — no AI context window can use a 4,000-line spec.
+- **NEVER** reproduce source code, SQL schemas, or type definitions inline.
+  Reference file paths instead (e.g., "see `src/engine/db/migrations/002.sql`
+  lines 48-70"). The code is the source of truth; duplicated snippets go stale.
 - If a requirement is ambiguous and you cannot resolve it by reading the code, state the ambiguity explicitly in an **Open Questions** section rather than guessing. Unclear specs lead to incorrect implementations.
 
 ## Specification Process
@@ -81,6 +88,12 @@ Write the specification using the formats below.
 3. **Write acceptance criteria** — Given/When/Then scenarios that define "done."
 4. **Define non-functional requirements** — Performance, security, accessibility where relevant.
 5. **List open questions** — Any unresolved decisions or unknowns that need stakeholder input.
+6. **Check length** — Count lines. If the draft exceeds 200 lines, split into
+   sub-specs by feature boundary. Create a parent overview (≤50 lines) linking
+   the sub-specs. Each sub-spec must be independently loadable.
+7. **Reference, don't reproduce** — Scan your draft for inline code blocks
+   containing schemas, SQL, type definitions, or configuration. Replace with
+   file path references and brief descriptions of what's there.
 
 ### Phase 4: Review
 
@@ -190,15 +203,29 @@ When relevant, include these categories using EARS format:
 Present specifications in this structure:
 
 ```markdown
-# Specification: [Feature Name]
+# Feature: [Name]
+**Version:** v0.X.0
+**Status:** planned
+**Last Updated:** YYYY-MM-DD
 
-## Overview
-Brief description of the feature and its purpose (2-3 sentences).
+## Intent
+[Problem statement + why — what exists now, what should change, who is affected]
 
-## Context
-- Current state: [what exists now, based on codebase investigation]
-- Desired state: [what should change]
-- Stakeholders: [who is affected]
+## Scope
+**In scope:** ...
+**Out of scope:** ...
+
+## Acceptance Criteria
+[Given/When/Then scenarios — one behavior per scenario, concrete values]
+
+## Key Files
+[File paths relevant to implementation — always populated from Phase 1 discovery]
+
+## Schema / Data Model
+[Reference to migration files + brief description, NOT full DDL]
+
+## API Endpoints
+[Table format: Method | Path | Description]
 
 ## Requirements
 
@@ -212,19 +239,8 @@ NFR-1: [EARS requirement]
 NFR-2: [EARS requirement]
 ...
 
-## Acceptance Criteria
-
-### [Requirement Group]
-Scenario: ...
-  Given ...
-  When ...
-  Then ...
-
-## Behavioral Changes
-[Requirements that change existing system behavior. For each, state:]
-- Current behavior: [what the system does now, with file:line evidence]
-- Specified behavior: [what the spec requires instead]
-- Impact: [who/what is affected — API consumers, UI, downstream services]
+## Dependencies
+- [External system or module this feature depends on]
 
 ## Open Questions
 [Group related unknowns. For each question, provide:]
@@ -233,9 +249,6 @@ Scenario: ...
    - Option B: [description] — [trade-off]
    - Recommendation: [if you have one, with reasoning]
 
-## Dependencies
-- [External system or module this feature depends on]
-
 ## Evidence
 - **Confirmed**: [Behavior verified in code — file path, line number, what was observed]
 - **Inferred**: [Behavior assumed from patterns, naming, or incomplete evidence — state the basis and flag for validation]

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/statusline-config.md

@@ -127,11 +127,11 @@ For longer commands, save a script to `~/.claude/statusline-command.sh`:
 }
 ```
 
-## Project-Specific Awareness
+## Existing Status Line Detection
 
-This workspace uses a custom status line feature (`ccstatusline`) with a wrapper at `/usr/local/bin/ccstatusline-wrapper`. If the user wants to modify the existing status line, check:
+If a custom status line feature (`ccstatusline`) is installed, check for a wrapper script. To find it:
 1. Current settings: Read `~/.claude/settings.json` for the active `statusLine` configuration
-2. Wrapper script: Read `/usr/local/bin/ccstatusline-wrapper` if it exists
+2. Wrapper script: Run `which ccstatusline-wrapper` to locate it, then read it if found
 3. Feature config: Check `.devcontainer/features/ccstatusline/` for the feature definition
 
 ## Workflow

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/agents/test-writer.md

@@ -183,6 +183,9 @@ go test -v ./path/to/package/...
 - **Ambiguous scope**: If the user says "test this" without specifying what, check if they have a file open or recently discussed a specific module. If unclear, ask which module or file to target.
 - **No test framework found**: Report this explicitly, recommend a framework based on the project's language, and ask the user how to proceed before writing anything.
 - If you cannot determine expected behavior for a function (no docs, no examples, unclear logic), state this explicitly in your output and write tests for the behavior you *can* verify, noting the gaps.
+- **Spec-linked testing**: When specs exist in `.specs/`, check if acceptance
+  criteria are defined for the area being tested. Report which criteria your tests
+  cover and which remain untested, so the orchestrator can update spec status.
 - **Always report** what you tested, what you discovered, and any bugs found in the source code.
 
 ## Output Format