Feature

Feature

One entry point for feature work, two modes:

• MODE=existing (old /add-feature path): the feature goes into an established codebase whose conventions are already known. No external research needed → Codex-direct scope → design → plan.
• MODE=greenfield (old /start-feature path): a large or new feature that needs external research and parallel design → Agent Teams (Researcher + Architect) with bidirectional communication.

Both modes converge on a shared Phase 3: user approval + complexity-routed implementation.

Preflight: ensure codex CLI is current (see codex-system skill).

/feature <feature description>
    | MODE determination (AskUserQuestion when ambiguous)
    ├─ MODE=existing   : Phase 1E SCOPE  -> Phase 2E DESIGN (Codex direct)
    └─ MODE=greenfield : Phase 1G UNDERSTAND -> Phase 2G RESEARCH & DESIGN (Agent Teams)
    | Phase 3 (shared): PLAN, APPROVE & IMPLEMENT
    SIMPLE   (1-3 files, <50 LOC) -> Codex danger-full-access direct
    MODERATE (3-5 files)          -> Codex danger-full-access + /team-execute --review-only
    COMPLEX  (5+ files)           -> /team-execute (implement + review)

Mode Determination (always first)

Decide the MODE before anything else. Signals:

If the signals are mixed or unclear, ask via AskUserQuestion — do NOT guess:

question: "Which feature mode applies?"
multiSelect: false
options:
  - label: "existing"
    description: "Add to an established codebase; conventions known; no external research (old /add-feature)."
  - label: "greenfield"
    description: "Large/new feature; needs external research and parallel design via Agent Teams (old /start-feature)."

When NOT to Use

• Bug diagnosis where root cause is unclear → /troubleshoot
• Executing an already-approved implementation plan → /team-execute
• Feasibility unknown / go-no-go decision needed first → /spike
• Truly trivial changes (single function, <10 LOC) → edit directly, skip this skill

Full skill routing: AGENTS.md section "Routing Policy".

Common Protocols (both modes)

Step 0: Read PROGRESS.md (always first)

Before anything else, if PROGRESS.md exists at the repository root, read it. It is the rolling summary of the latest 5 checkpoints (maintained by /checkpointing) and carries the most recent session context, in-progress work, and the "将来のアクション" (next actions) from prior sessions. Use it to ground the new feature in what already happened and to avoid re-deciding settled questions. If it is absent (fresh repo), skip this step.

Step 0-b: Resolve the Workspace

Resolve this feature's paths once. The title becomes file and directory names, so give it a short English descriptor of the feature — not the user's raw wording, which the Language Protocol keeps out of paths:

python3 .claude/skills/_shared/workspace.py \
  --skill feature --title "<short English title>" --create

The JSON on stdout carries slug, team_name, and paths (brief, codebase_scan, research, state_input, team_dir). From here on, every {slug} / {team-name} / output path in this skill — and the /team-execute handoff in Route C — MUST come from this JSON verbatim, never be re-derived by hand: two independently hand-derived slugs are exactly how cross-phase artifacts drift out of sync.

Requirements Gathering

Ask the user to clarify:

1. Purpose / feature description: What should the feature do? What do you want to achieve?
2. Expected behavior: How should it work from the user's perspective?
3. Scope boundaries: What to include / exclude?
4. Technical preferences / constraints: Specific libraries, patterns, or constraints?
5. Success criteria: How do you determine the feature is complete?
6. Final design (greenfield): What form should the result take?

Opus Subagent Codebase Scan

Main orchestrator context is precious — large-scale codebase scanning is always delegated to general-purpose-opus (Opus, 1M context):

Task tool:
  subagent_type: "general-purpose-opus"
  prompt: |
    Analyze this codebase for feature: {feature description}

    Tasks (MODE=existing — affected-area scan):
    1. Identify the areas relevant to this feature:
       - Which modules/files will be affected?
       - What are the existing patterns in those areas?
       - What interfaces/contracts exist that the feature must conform to?
    2. Analyze existing conventions:
       - Code patterns (naming, structure, error handling)
       - Test patterns (test location, fixture usage, assertion style)
       - Import and dependency patterns
    3. Map dependencies:
       - What does the affected code depend on?
       - What depends on the affected code? (downstream consumers)
       - Are there shared utilities or base classes to leverage?

    Tasks (MODE=greenfield — comprehensive scan):
    - Directory structure and organization
    - Key modules and their responsibilities
    - Existing patterns and conventions
    - Dependencies and tech stack
    - Test structure

    Use Glob, Grep, and Read tools to investigate thoroughly.

    Save analysis to the `codebase_scan` path from Step 0-b (`.claude/docs/research/feature-{slug}-codebase.md`).
    Return concise summary (5-7 key findings).

Claude may supplement the subagent's analysis with targeted Glob/Grep/Read on specific files.

Codex Consult Protocol

Every Codex consultation in this skill goes through the shared wrapper instead of a raw codex exec call, so a crashed CLI is never silently mistaken for an empty answer. Write the prompt body to a file under the workspace (.claude/logs/codex/prompt-{label}.md, beside where the wrapper writes the response), then invoke. The wrapper creates its log directory only after it reads the prompt file, so create the directory first — otherwise the heredoc write fails in a fresh clone and the consult reads nothing (or a stale prompt from a previous label):

mkdir -p .claude/logs/codex
# write the prompt body to .claude/logs/codex/prompt-{label}.md, then:
python3 .claude/skills/_shared/codex_consult.py \
  --prompt-file .claude/logs/codex/prompt-{label}.md --label {label} --sandbox read-only

Read the answer from the JSON output's response_file path. Exit codes: 0 the call succeeded — read response_file; 1 bad args; 2 codex CLI not on PATH; 3 codex exited non-zero or timed out — inspect error and stderr_file before retrying or escalating.

Sandbox: read-only for every analysis/design/validation consult below; Phase 3 implementation (Route A/B) uses --sandbox danger-full-access instead — called out again at that call site.

Prompts below show only the prompt body (Objective / Context / Constraints / Output format) — that is the file content for --prompt-file. MODE=existing consultations are MANDATORY — do not skip them. The most important input to every Codex prompt is the existing codebase patterns from the Opus subagent scan — always include them.

DESIGN.md Update

In both modes, record the feature's architecture decisions in .claude/docs/DESIGN.md (the macro 要件定義書) before presenting the plan — never by editing the file directly. DESIGN.md is user-owned and, in MODE=greenfield, has two writers (the Architect in Phase 2G and the lead in Phase 3); a hand edit loses the atomic replace and the concurrent-modification guard, and one writer silently overwrites the other. Every write goes through the shared writer, exactly as design-tracker does.

Write the typed input JSON to .claude/logs/design-input-{slug}.json (slug from Step 0-b, so two features cannot collide on one input file):

{
  "decisions": [
    {"decision": "{design decision}", "rationale": "{why}", "alternatives": "{what was rejected}"}
  ],
  "tech_choices": [
    {"area": "{area}", "technology": "{library or tool}", "rationale": "{why}", "alternatives": "{rejected}"}
  ],
  "section_updates": [
    {"heading": "## アーキテクチャ (Architecture)", "content": "- {integration point}: {how the feature connects}"}
  ]
}

Table rows go through their typed key — decisions, requirements, nfr, tech_choices, agent_roles — which places the row in the right table and escapes | in every cell. Hand-writing a table row as section_updates content is refused. Use section_updates only for prose sections (Architecture overview, Constraints, TODO / Open Questions).

Run the dry-run, review the preview, then apply:

python3 .claude/skills/_shared/update_design.py \
  --input .claude/logs/design-input-{slug}.json
# Review the preview file path in the JSON output, then:
python3 .claude/skills/_shared/update_design.py \
  --input .claude/logs/design-input-{slug}.json --apply --require-change

Verify "ok": true and "result": "applied". --require-change makes a no-op result (every row a duplicate, or an empty payload) exit 2, so this step can never report "recorded" for a run that wrote nothing. Exit 1 is a bad input schema; exit 2 DESIGN.md is missing or structurally invalid (run /init) or the run was a no-op; exit 3 DESIGN.md changed under you (concurrent modification) or the write failed — re-read DESIGN.md, drop what the other writer already recorded, and re-run the dry-run before applying again.

Ordering in MODE=greenfield: the Architect teammate writes its design decisions during Phase 2G through this same script; the lead writes only after both teammates have finished (Phase 3 Step 3), and records only what the Architect did not.

Shared State Update

Append feature context to .claude/STATE.md for cross-session persistence, following .claude/rules/agent-state.md. Use the shared writer script for a deterministic, atomic update; never edit root AGENTS.md.

Gather these fields from the planning phases:

• Context: Goal (1-2 sentences), Key files (new/modified), Dependencies, Complexity (SIMPLE / MODERATE / COMPLEX)
• Architecture: Key decisions from Codex / Architect
• Library Constraints (greenfield) or Codex Validation (existing)
• Integration Points and Decisions with rationale

Write the input JSON to the state_input path from Step 0-b (.claude/logs/state-input-{slug}.json):

{
  "title": "{feature name}",
  "sections": [
    {"heading": "Context", "content": "- Goal: ...\n- Key files: ...\n- Dependencies: ...\n- Complexity: MODERATE"},
    {"heading": "Architecture", "content": "- {decisions}"},
    {"heading": "Decisions", "content": "- {Decision 1}: {rationale}"}
  ]
}

Run dry-run, review the preview, then apply:

python3 .claude/skills/_shared/append_state_block.py \
  --type feature --input .claude/logs/state-input-{slug}.json
# Review the preview file path in the JSON output, then:
python3 .claude/skills/_shared/append_state_block.py \
  --type feature --input .claude/logs/state-input-{slug}.json --apply

Verify "ok": true and "progress_tracker_preserved": true in the output. Exit code 2 means the state structure is invalid; stop before writing.

Timing: MODE=greenfield writes this at plan time (Phase 3); MODE=existing may defer it to post-implementation. Either way it is written exactly once per feature.

Work Logs (Agent Teams roles)

All teammates spawned in MODE=greenfield write their work log to .claude/logs/agent-teams/{team-name}/{teammate}.md per the shared format: .claude/skills/_shared/work-log-format.md.

MODE=existing — Phase 1E: SCOPE (Opus Subagent + Codex + Claude Lead)

Understand the feature's scope and impact on the existing codebase: run the Opus subagent scan (common protocol, existing task list) and consult Codex for scope and impact analysis, while Claude clarifies requirements with the user (common protocol).

Codex Scope & Impact Analysis (MANDATORY)

Via the Codex consult protocol:

Objective: Analyze the scope and impact of adding this feature to the existing codebase.
Context:
- Feature: {feature description}
- Affected modules: {from Opus subagent analysis}
- Existing patterns: {from Opus subagent analysis}
- Dependencies: {from Opus subagent analysis}
Constraints:
- Assess how many files need to change and estimate LOC
- Classify complexity: SIMPLE (1-3 files, <50 LOC), MODERATE (3-5 files), COMPLEX (5+ files)
- Identify integration points where the feature connects to existing code
- Flag risks: breaking changes, performance concerns, test coverage gaps
Output format:
## Scope Assessment
## Complexity Classification (SIMPLE / MODERATE / COMPLEX)
## Integration Points
## Affected Files (with change type: new / modify)
## Risks and Concerns
## Recommended Approach

Use Codex's complexity classification to determine the implementation route in Phase 3.

Create Feature Brief

Combine user requirements + codebase analysis + Codex scope assessment into a Feature Brief following the MODE=existing template in references/brief-templates.md, and write it to the brief path from Step 0-b (.claude/docs/research/feature-{slug}-brief.md).

The brief is the primary cross-phase artifact: it feeds all three Phase 2E Codex prompts, Phase 3, the Route A implementation prompt, and the /team-execute handoff. Interpolating it from conversation context is how a half-filled brief reaches three Codex prompts undetected — every downstream step reads the file.

Validate it before leaving this phase:

python3 .claude/skills/_shared/validate_doc.py \
  --contract feature-brief --file .claude/docs/research/feature-{slug}-brief.md

Exit 0 every required section is present (the MODE=existing / MODE=greenfield variant is auto-detected from the headings); 1 bad args or the file is unreadable — most often it was never written; 2 a required section is missing, listed in sections_missing. Do not continue to Phase 2E on a non-zero exit.

The ### Complexity Classification (from Codex) section is where the decided classification is recorded once. Phase 3's presentation and route selection read it from this file rather than re-typing it, so a MODERATE assessment cannot be presented and then routed as SIMPLE. Codex decides the classification; only its propagation is mechanical.

MODE=existing — Phase 2E: DESIGN (Codex Architecture + Plan + Validation)

Codex designs the architecture, creates an implementation plan, and validates completeness. All three consultations are MANDATORY.

Unlike MODE=greenfield which uses Agent Teams (Researcher + Architect) for design, MODE=existing uses Codex directly because the patterns and conventions are already established.

Step 1: Codex Architecture Design (MANDATORY)

Objective: Design the architecture for adding this feature to the existing codebase.
Context:
- Feature Brief: contents of .claude/docs/research/feature-{slug}-brief.md (from Phase 1E)
- Existing patterns: {conventions from codebase scan}
- Integration points: {from Codex scope analysis}
Constraints:
- Follow existing codebase conventions exactly (naming, structure, patterns)
- Minimize changes to existing code (prefer extension over modification)
- Maintain backward compatibility
- Design for testability
Output format:
## Architecture Design
## Module Structure (new files and modifications)
## Interface Design (function signatures, class APIs)
## Data Flow
## Error Handling Strategy
## Test Strategy

Step 2: Codex Implementation Plan (MANDATORY)

Objective: Create a step-by-step implementation plan for this feature.
Context:
- Feature Brief: contents of .claude/docs/research/feature-{slug}-brief.md (from Phase 1E)
- Architecture Design: {from Step 1}
- Complexity: {SIMPLE / MODERATE / COMPLEX}
Constraints:
- Order steps by dependency (what must be built first)
- Each step should be independently testable
- Include test writing as explicit steps (TDD where possible)
- Keep individual steps small and focused
Output format:
## Implementation Steps (ordered by dependency)
## File Changes (per step: file path, change type, description)
## Test Plan (per step: what to test)
## Dependencies Between Steps
## Estimated Effort per Step

Step 3: Codex Validation (MANDATORY)

Objective: Validate this implementation plan for completeness, correctness, and risk.
Context:
- Feature Brief: contents of .claude/docs/research/feature-{slug}-brief.md
- Architecture Design: {from Step 1}
- Implementation Plan: {from Step 2}
- Existing codebase patterns: {from Phase 1E}
Constraints:
- Check for missing edge cases or error handling
- Verify the plan maintains backward compatibility
- Ensure test coverage is adequate
- Identify potential integration issues
- Check that the plan follows existing conventions
Output format:
## Validation Result (PASS / NEEDS_REVISION)
## Missing Coverage
## Backward Compatibility Check
## Convention Compliance
## Integration Risks
## Additional Test Cases Recommended
## Revised Steps (if NEEDS_REVISION)

If Codex returns NEEDS_REVISION, update the plan and re-validate before proceeding.

Then update DESIGN.md (common protocol) and continue to Phase 3.

MODE=greenfield — Phase 1G: UNDERSTAND (Opus Subagent + Claude Lead)

Analyze the codebase with the Opus subagent scan (common protocol, greenfield task list) while Claude gathers requirements from the user (common protocol).

Create Project Brief

Combine codebase understanding + requirements into a Project Brief following the MODE=greenfield template in references/brief-templates.md, and write it to the brief path from Step 0-b (.claude/docs/research/feature-{slug}-brief.md).

Validate it before spawning the team — a teammate that starts from a truncated brief researches the wrong thing, and nothing downstream would notice:

python3 .claude/skills/_shared/validate_doc.py \
  --contract feature-brief --file .claude/docs/research/feature-{slug}-brief.md

Exit 0 every required section is present (variant auto-detected); 1 bad args or unreadable/never written; 2 a required section is missing, listed in sections_missing.

Phase 2G teammates receive the brief path as shared context and read the file, so lead and teammates work from the same bytes.

MODE=greenfield — Phase 2G: RESEARCH & DESIGN (Agent Teams — Parallel)

Launch Researcher and Architect in parallel via Agent Teams with bidirectional communication.

Key difference from subagents: Teammates can communicate with each other. Researcher's findings change Architect's design, and Architect's requests trigger new research.

Team Setup

Create an agent team for project planning: {feature}

Spawn two teammates:

1. **Researcher** — Uses WebSearch/WebFetch for external research (Opus 1M context)
   Prompt: "You are the Researcher for project: {feature}.

   Your job: Research external information needed for this project.

   Project Brief: read .claude/docs/research/feature-{slug}-brief.md

   Tasks:
   1. Research libraries and tools: usage patterns, constraints, best practices
   2. Find latest documentation and API specifications
   3. Identify common pitfalls and anti-patterns
   4. Look for similar implementations and reference architectures

   How to research:
   - Use WebSearch for comprehensive research:
     WebSearch: '{topic} best practices constraints recommendations'
   - Use WebFetch for targeted documentation lookup

   Save all findings to the `research` path from Step 0-b (.claude/docs/research/{slug}.md).
   Save library docs to .claude/docs/libraries/{library}.md

   Communicate with Architect teammate:
   - Share findings that affect design decisions
   - Respond to Architect's research requests
   - Flag constraints that limit implementation options

   IMPORTANT — Work Log:
   When ALL your tasks are complete, write your work log to
   .claude/logs/agent-teams/{team-name}/researcher.md per the shared format:
   .claude/skills/_shared/work-log-format.md
   Role-specific sections (between Tasks Completed and Communication):
   ## Sources Consulted
   - {URL or source}: {what was found}
   ## Key Findings
   - {finding}: {relevance to project}
   "

2. **Architect** — Uses Codex CLI for design and planning
   Prompt: "You are the Architect for project: {feature}.

   Your job: Use Codex CLI to design the architecture and create implementation plan.

   Project Brief: read .claude/docs/research/feature-{slug}-brief.md

   Tasks:
   1. Design architecture (modules, interfaces, data flow)
   2. Select patterns (considering existing codebase conventions)
   3. Create step-by-step implementation plan with dependencies
   4. Identify risks and mitigation strategies

   How to consult Codex:
   Write the question to .claude/logs/codex/prompt-<topic>.md, then:
   python3 .claude/skills/_shared/codex_consult.py --prompt-file .claude/logs/codex/prompt-<topic>.md --label <topic> --sandbox read-only
   Read the answer from the JSON output's response_file.

   Record architecture decisions in .claude/docs/DESIGN.md through the shared
   writer — never by editing the file. The lead writes the same document in
   Phase 3, so a direct edit is a lost update:
   write the typed JSON to .claude/logs/design-input-{slug}-architect.json
   (keys: decisions / tech_choices / agent_roles / section_updates — table rows
   only through their typed key), then:
   python3 .claude/skills/_shared/update_design.py --input .claude/logs/design-input-{slug}-architect.json
   # review the preview path in the JSON output, then:
   python3 .claude/skills/_shared/update_design.py --input .claude/logs/design-input-{slug}-architect.json --apply --require-change
   Verify "ok": true and "result": "applied". Exit 2 = invalid structure or a
   no-op; exit 3 = DESIGN.md changed concurrently — re-read it and redo the
   dry-run before applying. Report an exit 2 or 3 in your work log.

   Communicate with Researcher teammate:
   - Request specific library/tool research
   - Share design constraints that need validation
   - Adjust design based on Researcher's findings

   IMPORTANT — Work Log:
   When ALL your tasks are complete, write your work log to
   .claude/logs/agent-teams/{team-name}/architect.md per the shared format:
   .claude/skills/_shared/work-log-format.md
   Role-specific sections (between Tasks Completed and Communication):
   ## Design Decisions
   - {decision}: {rationale}
   ## Codex Consultations
   - {question asked to Codex}: {key insight from response}
   "

Wait for both teammates to complete their tasks.

Verify the Team Run (before Phase 3)

Both teammates were told to write a work log; a teammate that died mid-task, or wrote a log missing Issues Encountered, is otherwise indistinguishable from success — and Phase 3 would then synthesize from an incomplete run:

python3 .claude/skills/_shared/validate_doc.py \
  --contract work-log --dir .claude/logs/agent-teams/{team-name}/ --expect-files 2

Gate on files_failed == 0. Exit 0 both logs exist and satisfy the contract; 1 bad args or the team directory does not exist; 2 a required section is missing (see results[].sections_missing) or the directory does not hold exactly 2 logs — --expect-files 2 is what makes "no teammate wrote a log" distinguishable from "all logs valid". Do not proceed on a non-zero exit: find out what the missing teammate did or did not do first.

Why Bidirectional Communication Matters

Example interaction flow:

Researcher: "httpx has a connection pool limit of 100 by default"
    → Architect: "Need to add connection pool config to design"
    → Architect: "Also research: does httpx support HTTP/2 multiplexing?"
    → Researcher: "Yes, via httpx[http2]. Requires h2 dependency."
    → Architect: "Updated design to use HTTP/2 for the API client module"

Without Agent Teams (old subagent approach), this would require:

1. Researcher subagent finishes → returns summary
2. Claude reads summary → creates new Codex subagent prompt
3. Codex subagent finishes → returns summary
4. If Codex needs more info → another researcher subagent round

Agent Teams collapses this into a single parallel session with real-time interaction.

Phase 3 (shared): PLAN, APPROVE & IMPLEMENT

Both modes converge here: synthesize, get user approval, then route implementation by complexity.