Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
placeholder
4 changes: 2 additions & 2 deletions .claude/agents/quality-engineer.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,11 +268,11 @@ Your goal is to prevent quality issues through intelligent pattern enforcement w

## Validation Mode

When dispatched via `/team-plan` or `/build` to validate completed work, the quality-engineer operates in **validation mode** -- a read-only inspection workflow focused on verifying builder output against acceptance criteria.
When dispatched via `/blueprint` or `/impl` to validate completed work, the quality-engineer operates in **validation mode** -- a read-only inspection workflow focused on verifying builder output against acceptance criteria.

### When Activated

- Dispatched as a validator by team orchestration commands (`/team-plan`, `/build`)
- Dispatched as a validator by team orchestration commands (`/blueprint`, `/impl`)
- Assigned a task whose purpose is to verify or validate another agent's completed work
- Task description references "validate", "verify", or "inspect" against acceptance criteria

Expand Down
164 changes: 91 additions & 73 deletions .claude/commands/adr.md
Original file line number Diff line number Diff line change
@@ -1,77 +1,95 @@
---
description: Create or review Architecture Decision Records
model: opus
model: sonnet
---

# Architecture Decision Record

Create or update an Architecture Decision Record (ADR) documenting a technical decision, its rationale, and compatibility with existing decisions.

## When to use
- Implementation deviates from the spec
- A significant technical decision is made that affects future work
- User says "create an ADR", "document this decision", "we're changing approach"
- Detected at a milestone checkpoint during impl-start

## Model Routing

This command routes to the architecture category model:

| Environment | Model | Rationale |
|---|---|---|
| Claude Code (work) | sonnet | ADRs require careful reasoning about compatibility |
| OpenCode (home) | gemini-2.5-flash | Architecture decisions need structured analysis |

## Workflow

**CRITICAL:** If $ARGUMENTS is empty, STOP here and ask user: "What decision would you like to document as an ADR?" Do NOT read any files until a description is provided.

### Step 1: Load context
1. If $ARGUMENTS is NOT empty, user has described the ADR topic: "$ARGUMENTS"
2. If $ARGUMENTS is empty, ask: "What technical decision would you like to document as an ADR?"
3. Do NOT read Spec.md or other files until description is obtained
4. Once you have a description, then check if working within a feature and read its Spec.md
5. Check if this ADR documents a spec deviation
6. Load relevant ADRs in Context/Decisions/

### Step 2: Determine ADR type
1. **New decision:** No existing ADR covers this area
2. **Supersed:** Replacing a previous ADR (document why)
3. **Refinement:** Updating an existing decision while preserving original

### Step 3: Determine ADR number
1. Find highest NNNN in existing ADR filenames
2. Assign NNNN+1

### Step 4: Draft ADR content
1. **Context:** What problem or situation motivated this decision
2. **Decision:** What was decided (1-2 sentences, then details)
3. **Consequences:** Benefits, trade-offs, and risks
4. **Compatibility:** Check against overlapping ADRs
- Same files affected
- Same feature area
- Same architectural concern
5. **Related:** Link to feature, files affected, spec section

### Step 5: Contradiction detection
This is critical. Compare new ADR against all accepted (non-superseded) ADRs:

**For each overlapping ADR:**
- Present the overlap to user
- Require resolution:
- "Compatible because [reason]" — decisions coexist
- "Supersedes ADR-XXXX" — new replaces old
- "Need to rethink" — reconsider the decision

**If no overlaps:** Document "No overlapping accepted ADRs found"

### Step 6: Write ADR file
1. Create `Context/Decisions/NNNN-decision-title.md` (kebab-case)
2. Fill all sections including completed Compatibility section
3. Set status to "Proposed" or "Accepted" based on context

### Step 7: Update related artifacts
If documenting a spec deviation, update the feature's Spec.md:
- Add entry to Revision History table
- Update affected Testable Assertions status to "Superseded by ADR-NNNN"
- Note ADR number for commit message
# Architecture Decision Record

Create or update an Architecture Decision Record (ADR) documenting a technical decision, its rationale, and compatibility with existing decisions.

## When to use
- Implementation deviates from the spec
- A significant technical decision is made that affects future work
- User says "create an ADR", "document this decision", "we're changing approach"
- Detected at a milestone checkpoint during impl-start

## Model Routing

This command routes to the architecture category model:

| Environment | Model | Rationale |
|---|---|---|
| Claude Code (work) | sonnet | ADRs require careful reasoning about compatibility |
| OpenCode (home) | gemini-2.5-flash | Architecture decisions need structured analysis |

## Workflow

**CRITICAL:** If $ARGUMENTS is empty, STOP here and ask user: "What decision would you like to document as an ADR?" Do NOT read any files until a description is provided.

### Step 1: Load context
1. If $ARGUMENTS is NOT empty, user has described the ADR topic: "$ARGUMENTS"
2. If $ARGUMENTS is empty, ask: "What technical decision would you like to document as an ADR?"
3. Do NOT read Spec.md or other files until description is obtained
4. Once you have a description, then check if working within a feature and read its Spec.md
5. Check if this ADR documents a spec deviation
6. Load relevant ADRs in Context/Decisions/

### Step 2: Determine ADR type
1. **New decision:** No existing ADR covers this area
2. **Supersed:** Replacing a previous ADR (document why)
3. **Refinement:** Updating an existing decision while preserving original

### Step 3: Determine ADR number
1. Find highest NNNN in existing ADR filenames
2. Assign NNNN+1

### Step 4: Draft ADR content
1. **Context:** What problem or situation motivated this decision
2. **Decision:** What was decided (1-2 sentences, then details)
3. **Consequences:** Benefits, trade-offs, and risks. For non-trivial ADRs, consult the Advisor tool before writing this section:

```bash
cat > /tmp/cortex-adr-consequences-<NNNN>.md <<'EOF'
Decision being documented:
[1-2 sentence summary of the decision]

Known context and constraints:
[paste Context section of the draft ADR]

Question: what are the two most load-bearing consequences (one benefit,
one risk) that this ADR must name to be honest about the trade-off?
Respond as enumerated bullets.
EOF

bun run .claude/hooks/advisor/advisor-cli.ts --question-file /tmp/cortex-adr-consequences-<NNNN>.md
```

Exit 0: fold the Advisor's response into the Consequences section. Exit 2: draft in-thread without the consult.
4. **Compatibility:** Check against overlapping ADRs
- Same files affected
- Same feature area
- Same architectural concern
5. **Related:** Link to feature, files affected, spec section

### Step 5: Contradiction detection
This is critical. Compare new ADR against all accepted (non-superseded) ADRs:

**For each overlapping ADR:**
- Present the overlap to user
- Require resolution:
- "Compatible because [reason]" — decisions coexist
- "Supersedes ADR-XXXX" — new replaces old
- "Need to rethink" — reconsider the decision

**If no overlaps:** Document "No overlapping accepted ADRs found"

### Step 6: Write ADR file
1. Create `Context/Decisions/NNNN-decision-title.md` (kebab-case)
2. Fill all sections including completed Compatibility section
3. Set status to "Proposed" or "Accepted" based on context

### Step 7: Update related artifacts
If documenting a spec deviation, update the feature's Spec.md:
- Add entry to Revision History table
- Update affected Testable Assertions status to "Superseded by ADR-NNNN"
- Note ADR number for commit message
37 changes: 29 additions & 8 deletions .claude/commands/blueprint.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
description: Full 4-phase planning: Spec, Tech, Steps with team orchestration
model: opus
model: sonnet
---

# Full Planning Workflow
Expand Down Expand Up @@ -29,12 +29,31 @@ Generate a complete 4-phase plan for major features or complex tasks. Creates Sp
1. Determine feature number (next available NNN in Context/Features/)
2. Use the `plan-spec` skill to create `Context/Features/NNN-FeatureName/Spec.md`
3. Include: Overview, Problem Statement, User Stories, Requirements (Must/Should/Won't), Testable Assertions, Open Questions, Dependencies
4. Present to user for review and approval before proceeding
4. Present to user for review and approval before proceeding

### Step 3: Create Tech.md (Phase 2)
1. Use the `plan-research` skill to create `Context/Features/NNN-FeatureName/Tech.md`
2. Research and document: Architecture overview, key decisions with options considered, stack-specific details, integration points, risks and unknowns
3. Create ADRs for significant architectural decisions
3. Create ADRs for significant architectural decisions. For each significant decision, consult the Advisor tool before finalising the ADR:

```bash
cat > /tmp/cortex-adr-<short-name>.md <<'EOF'
Context (from Spec.md and research so far):
[paste the relevant requirement, constraint, or trade-off]

Options considered:
[enumerate the options and their observable consequences]

Question: which option should the ADR accept, and what are the two
most load-bearing consequences the Consequences section must name?
Respond as enumerated bullets.
EOF

bun run .claude/hooks/advisor/advisor-cli.ts --question-file /tmp/cortex-adr-<short-name>.md
```

- Exit 0: fold the Advisor's enumerated response into the ADR draft.
- Exit 2: Advisor unavailable; draft the ADR in-thread without the consult.
4. Present to user for review and approval before proceeding

### Step 4: Create Steps.md (Phase 3)
Expand All @@ -54,18 +73,20 @@ Present all three documents for review:
- Spec.md summary: key requirements and assertions
- Tech.md summary: architecture decisions and ADRs created
- Steps.md summary: task count, team composition, wave structure
- Estimated execution approach: `/impl` vs `/team-impl`

Confirm or adjust before proceeding to implementation.

Suggest next step:
- `/impl NNN` to execute via sub-agents
- `/team-impl NNN` to execute via Agent Teams (if cross-domain coordination needed)
### Step 6: Suggest execution command
ALWAYS end by recommending the most appropriate execution command with the feature number:
- `/impl NNN` -- default for most features (hub-and-spoke sub-agent orchestration)
- `/team-impl NNN` -- when cross-domain coordination is needed (peer-to-peer Agent Teams)

Choose based on the Steps.md content: if tasks span multiple stacks with tight integration points, recommend `/team-impl`. Otherwise recommend `/impl`.

## Rules
- Each phase requires user approval before proceeding to the next
- Do NOT skip phases or combine them
- If the feature is too small for 4-phase planning, suggest `/quick` instead
- ADRs are created during Phase 2 for any significant architectural decision
- Phase 3 must produce a Steps.md with team orchestration metadata
- Note any ADRs created during planning in the final summary
- Note any ADRs created during planning in the final summary
126 changes: 59 additions & 67 deletions .claude/commands/diagnose.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,70 +3,62 @@ description: Check project structure and Cortex health
model: sonnet
---

# Doctor: Context Engine Configuration

Display effective Context Engine configuration, showing model resolution and feature flags.

## Output

### Configuration Hierarchy

Show the config resolution order:

1. **Adapter defaults** — Built-in defaults from the adapter
2. **User config** — `~/.config/opencode/context-engine.jsonc` (OpenCode)
3. **Project config** — `.opencode/context-engine.jsonc` (current project)

Each level overrides the previous. The output should show which values come from which level.

### Model Routing

Show effective model assignment for all agents:

| Agent | Model | Source |
|---|---|---|
| build | `provider/model` | project/user/adapter |
| plan | `provider/model` | project/user/adapter |
| qa-python | `provider/model` | project/user/adapter |
| ... | ... | ... |

And categories:

| Category | Model | Source |
|---|---|---|
| quick | `provider/model` | project/user/adapter |
| planning | `provider/model` | project/user/adapter |
| ... | ... | ... |

### Feature Flags

| Feature | State | Source |
|---|---|---|
| parallel_qa | true/false | project/user/adapter |
| context_aware_compaction | true/false | project/user/adapter |
| notifications | true/false | project/user/adapter |

### Background Task Concurrency

```
Default concurrency: N
Provider limits:
- provider-name: M
```

### Disabled Components

```
Disabled agents: [list or "none"]
Disabled skills: [list or "none"]
```

## Implementation

1. Read and merge configs in priority order: adapter → user → project
2. For each agent and category, show the resolved value and its source
3. For each feature flag, show state and source
4. Display background task concurrency settings
5. Show any disabled agents/skills

Use the same config loading logic as the OpenCode plugin (`adapters/opencode/config.ts`).
# Diagnose: Cortex Project Health Check

Run a structured health check on the current project's Cortex configuration.

## Checks

### 1. Directory Structure
Verify required directories exist:
- [ ] `Context/Features/`
- [ ] `Context/Decisions/`
- [ ] `Context/Reviews/`
- [ ] `Context/Backlog/`
- [ ] `.cortex/`
- [ ] `.claude/hooks/`
- [ ] `.claude/agents/`
- [ ] `.claude/commands/`
- [ ] `.claude/skills/`

### 2. Configuration Files
Verify required files exist and are valid JSON/markdown:
- [ ] `CLAUDE.md` exists and has `## Active Work` section
- [ ] `.claude/settings.json` exists and has hooks configured
- [ ] `.claude/hooks/skill-activation/skill-rules.json` exists
- [ ] `.claude/hooks/skill-activation/agent-rules.json` exists

### 3. Hook Health
For each hook in `.claude/settings.json`:
- [ ] Script file exists at the declared path
- [ ] Script is valid TypeScript (run `bun check` or parse for syntax errors)
- [ ] No hardcoded secrets (scan for `sk-`, `ghp_`, `AKIA`, password patterns)

### 4. MCP Context Budget
Check MCP server count and tool count:
- Count enabled MCP servers in `.claude/settings.json` and `.mcp.json`
- Count total tools across all servers
- **WARN** if >10 servers enabled
- **WARN** if >80 tools active
- Display estimated context consumption

### 5. Session State
- [ ] `.cortex/session.md` -- report if active session exists
- [ ] `.cortex/backups/` -- report backup count and most recent
- [ ] `.cortex/patterns.md` -- report if pattern log exists and entry count

### 6. Active Work Consistency
- If CLAUDE.md lists an active feature, verify the corresponding
`Context/Features/NNN-Name/` directory exists
- Check for orphaned Steps.md files without matching Spec.md

## Output Format

| Check | Status | Details |
|-------|--------|---------|
| Directory structure | PASS/WARN/FAIL | Missing: [...] |
| Config files | PASS/WARN/FAIL | Invalid: [...] |
| Hook health | PASS/WARN/FAIL | Issues: [...] |
| MCP budget | PASS/WARN | Servers: N, Tools: N |
| Session state | INFO | Active/None, N backups |
| Active work | PASS/WARN | Consistency issues: [...] |
Loading