<project>/                    # e.g., m32rimm/
└── .claude/
    └── specs/
        └── <name>-<hash>/
            ├── manifest.json          # Execution config (machine-readable)
            ├── SPEC.md                # Human-readable spec
            ├── brainstorm/            # From /spec phase
            │   ├── MISSION.md
            │   ├── INVESTIGATION.md
            │   ├── DECISIONS.md
            │   └── CONCERNS.md
            └── components/            # Per-component context

{
  "name": "feature-name",
  "project": "project-name",
  "work_dir": "/path/to/project",
  "spec_dir": ".claude/specs/feature-abc123",
  "created": "2025-12-08",

  "complexity": 7,
  "risk_level": "medium",
  "risk_score": 9,

  "execution": {
    "mode": "standard",
    "reviewers": 4,
    "require_tests": true,
    "voting_gates": ["fix_strategy", "production_ready"]
  },

  "components": [
    {
      "id": "parser",
      "file": "path/to/parser.py",
      "depends_on": [],
      "complexity": "medium",
      "purpose": "Parse input data",
      "parallel_group": 1
    },
    {
      "id": "validator",
      "file": "path/to/validator.py",
      "depends_on": ["parser"],
      "complexity": "high",
      "purpose": "Validate against schema",
      "parallel_group": 2
    }
  ],

  "parallelization": {
    "skeleton_parallel": true,
    "implementation_parallel": true,
    "validation_parallel": false,
    "parallel_groups": [
      {
        "group": 1,
        "components": ["parser", "config"],
        "reason": "No dependencies between them"
      },
      {
        "group": 2,
        "components": ["validator"],
        "reason": "Depends on group 1"
      }
    ]
  },

  "agents": {
    "skeleton": "skeleton-builder",
    "implementation": "implementation-executor",
    "test_skeleton": "test-skeleton-builder",
    "test_implementation": "test-implementer",
    "validators": ["code-reviewer"],
    "project_validators": []
  },

  "project_config": {
    "extends": "m32rimm",
    "validators": ["mongo_validator", "import_validator", "general_validator"],
    "finding_validator": true,
    "validator_triggers": {
      "mongo_validator": "file uses: db., pymongo, DBOpsHelper, retry_run, businessObjects",
      "import_validator": "file in: imports/, or uses: data_importer"
    }
  },

  "quality": {
    "coverage_target": 95,
    "lint_required": true,
    "lint_command": "python-code-quality --fix",
    "security_scan": false
  },

  "gotchas": [
    "MongoDB aggregation has 16MB limit",
    "Must call flush() before mark_for_aggregation()"
  ],

  "validation_command": "python -m pytest tests/"
}

Example:
  A (no deps)     → Group 0
  B (no deps)     → Group 0   ← A and B run in PARALLEL
  C (depends A)   → Group 1
  D (depends B)   → Group 1   ← C and D run in PARALLEL (after A,B complete)
  E (depends C,D) → Group 2   ← E runs after C,D complete

{
  "parallelization": {
    "skeleton_parallel": true,       // skeleton-builder + test-skeleton-builder
    "implementation_parallel": true, // implementation-executor + test-implementer
    "validation_parallel": false,    // Multiple validators (be careful with edits)
    "max_concurrent": 4              // Max parallel agents
  }
}

{
  "project_config": {
    "extends": "m32rimm",
    "validators": [
      "mongo_validator",
      "import_validator",
      "general_validator"
    ],
    "finding_validator": true,
    "validator_triggers": {
      "mongo_validator": "file uses: db., pymongo, DBOpsHelper, retry_run, businessObjects",
      "import_validator": "file in: imports/, or uses: data_importer, insert_data_importer",
      "bo_structure_validator": "file creates: BO, or uses: upsert_bo, BOUpsert"
    },
    "agents_dir": ".claude/agents/"
  }
}

{
  "components": [
    {
      "id": "complex_import",
      "file": "imports/scanner/handler.py",
      "agents": {
        "implementation": "implementation-executor",
        "validators": ["mongo_validator", "import_validator", "general_validator"]
      }
    }
  ]
}

# Mission

## Goal
[Single sentence: what we're building and why]

## Success Criteria
- [ ] Measurable outcome 1
- [ ] Measurable outcome 2

## Non-Goals
- Thing we're explicitly NOT doing

## Constraints
- Hard requirement

# Investigation Findings

## Project Structure
[Tech stack, directory layout]

## Existing Patterns
- Auth: [how auth works]
- APIs: [API patterns]
- Testing: [test approach]

## Dependencies
- External: [packages]
- Internal: [modules this touches]

## Blast Radius
- Direct: [files we modify]
- Indirect: [files that import modified files]
- Transitive: [N files deep]

# Architectural Decisions

## Decision 1: [Topic]

**Choice:** [What we're doing]
**Rationale:** [Why]
**Alternatives:** [What else we considered]
**Consequences:** [Trade-offs]

## Parallelization Decision

**Parallel Groups:**
- Group 0: [components] - no dependencies
- Group 1: [components] - depends on group 0

**Rationale:** [Why this grouping]

## Agent Selection

**Project validators needed:**
- [validator]: [because X uses Y]

**Model overrides:**
- [component]: opus (complex judgment needed)

# Concerns & Gotchas

## Conflicts
- [Conflict with existing code]

## Hidden Complexity
- [Challenge that's not obvious]

## m32rimm-Specific Concerns
- [ ] DBOpsHelper flush() before aggregation
- [ ] subID filter on businessObjects queries
- [ ] retry_run on all mongo operations

## Risks
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk] | High | [Mitigation] |

# [Feature Name]

## Mission
[From MISSION.md]

## Components

| ID | File | Group | Validators |
|----|------|-------|------------|
| parser | parser.py | 0 | general |
| validator | validator.py | 1 | general, mongo |

## Execution Plan

## Validators Active
- mongo_validator (files use MongoDB)
- import_validator (files in imports/)
- general_validator (all files)
- finding_validator (filter false positives)

## Risk Assessment
- Score: 9/15 (Medium)
- Reviewers: 4
- Voting gates: fix_strategy, production_ready

## Gotchas
[From CONCERNS.md]