Plan Sprint

This command guides the sprint planning process.

Process

1. Assess Current State

Load and review:

• docs/CAPABILITIES.md

  - What the system should do (includes status per capability)

• docs/architecture/README.md

  - Implementation status by module

Identify gaps: What capabilities are not started or partial?

2. Propose Sprint Scope

Based on gaps and dependencies, propose what this sprint should deliver.

Scope can be:

• Part of one capability (e.g., "generated actors only, not arrivals")
• Parts of multiple capabilities (e.g., "basic actors + basic entities needed together")
• Infrastructure that enables capabilities (e.g., "config parsing before anything else")

Write a scope proposal:

## Proposed Scope

**Delivers:** [What this sprint produces]

**Capabilities touched:**
- actors: generated actors, properties (not arrivals, not lifecycle)
- entities: generated entities, properties

**Rationale:** [Why this scope makes sense—dependencies, complexity, coherence]

**Not included:** [What's explicitly deferred]

Present scope to user for approval before proceeding.

3. Load Detailed Context

Once scope is approved, load relevant docs:

• docs/architecture/README.md

  - See reading order for which docs to load

• docs/architecture/*.md

  - Design rationale and constraints

• docs/architecture/pending/*.md

  - Design doc for this feature (if one exists)

If a design doc exists in

pending/

4. Define Purpose and Success Criteria

Write a clear purpose statement:

• One sentence describing what this sprint delivers
• How an educator will use this capability
• Observable success criteria

5. Design Contracts

Use the architect agent to design interface contracts.

Each contract needs:

• Full function signature with type hints
• Complete docstring (Args, Returns, Raises)
• NO default parameters (Principle #7)
• NO scaffolding for future work (Principle #8)
• All error conditions documented
• NO implementation code — signatures and docstrings only

def function_name(
    param1: Type1,
    param2: Type2,
) -> ReturnType:
    """
    One-line summary.

    Args:
        param1: Description
        param2: Description

    Returns:
        Description

    Raises:
        ValueError: When X
    """
    ...

For modified functions, describe behavioral changes in the docstring. Do not show implementation diffs (for-loops, if-blocks, code to insert). The implementer writes the code; the contract says what the code should do.

Anti-scaffolding checklist:

• No

  # Future:

  comments in contracts
• No methods that will "do nothing for now"
• No precomputed data that won't be used this sprint
• Every loop body has real work (no

  pass

  placeholders)
• Every parameter is actually used

6. Break Into Phases

Divide work into independently testable phases:

Each phase must:

• Be independently testable
• Have a standalone demo script
• List explicit test cases (not just test files)
• Build on previous phases

7. Define Demo Requirements

Demo scripts live in

docs/sprints/current/demos/

For each phase, specify:

• What the demo script demonstrates
• Sample config (embedded in demo)
• Expected output/behavior
• Success criteria

8. Create Artifacts

Create

docs/sprints/current/spec.md

# Sprint: [Name]

## Purpose
[One sentence + educator use case]

## Scope

**Capabilities touched:**
- capability1: sub-capability A, sub-capability B
- capability2: sub-capability C

**Not included:** [What's deferred]

## Breaking Changes

Document any changes to existing public interfaces, field types becoming optional,
constructor signatures changing, or validator behavior changing. For each:
- What changes
- Why existing configs/code still work (or don't)

Omit this section if the sprint is purely additive.

## Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Contracts
[Function signatures with docstrings — no implementation code]

## Phases

### Phase 1: [Name]
**Delivers:** [What]
**Demo:** [What it proves]
**Contracts:** [Which functions from this phase]

**Files:**
| Action | File |
|--------|------|
| Modify | `packages/<pkg>/src/<module>.py` |
| Create | `packages/<pkg>/tests/<module>/test_<name>.py` |

**Tests:**
- Specific test case description (e.g., "Write single role twice: second overwrites first")
- Another specific test case
- Existing tests that must still pass

Test files go in the directory matching the code under test (e.g., `tests/journeys/` for journey code, `tests/config/rules/` for validation rules). Never create sprint-named test files or a `tests/sprints/` directory.

### Phase 2: [Name]
...

## What Doesn't Change

Explicit scope boundaries to prevent implementer drift. List functions, modules, or
behaviors that must NOT be modified even though they're adjacent to the work.

- [Function/module] stays as-is because [reason]
- [Existing behavior] is not affected because [reason]

## Module Changes Summary

Quick-reference table of all files touched across all phases:

| File | Change |
|------|--------|
| `path/to/file.py` | One-line summary of change |

Update

docs/sprints/current/state.yaml

sprint: sprint-name
started: YYYY-MM-DD
current_phase: 1
capabilities:
  - actors: [generated, properties]
  - entities: [generated, properties]
phases:
  1: {status: pending}
  2: {status: pending}

9. Update Status

After sprint completes:

• Update

  docs/CAPABILITIES.md

  status markers for touched capabilities
• Update

  docs/architecture/README.md

  Implementation Status table if modules changed
• Archive sprint to

  docs/sprints/archive/

Quality Checks Before Done

• Scope approved by user
• Purpose is clear and educator-focused
• Capabilities touched are explicit
• Breaking changes documented (or section omitted if purely additive)
• All contracts have full signatures + docstrings
• NO default parameters in any contract (Principle #7)
• NO scaffolding for future work (Principle #8)
• NO implementation code in contracts (signatures and docstrings only)
• Anti-scaffolding checklist passed
• Phases are independently testable
• Each phase has explicit test case bullets (not just file names)
• Demo requirements specified per phase
• "What Doesn't Change" section present
• Module Changes Summary present
• spec.md created
• state.yaml updated

Code Navigation

When exploring existing code during planning, use LSP tools instead of Grep for structural queries:

find_definition

Grep "def foo"

find_references

Grep "foo("

get_hover

Read

get_incoming_calls

Grep "function_name"

find_workspace_symbols

Glob

Grep

Reserve Grep for pattern searches (anti-patterns, TODOs, regex matching).

When to Use Architect Agent

Invoke the architect agent when you need to:

• Design complex interfaces
• Make architectural decisions
• Update architecture docs
• Resolve design ambiguities