Dev Sprint

Development Sprint

Every non-trivial task follows this workflow. No shortcuts.

1. Plan

Create a sprint directory and write the plan before touching code:

mkdir -p sprints/<sprint-name>

Write sprints/<sprint-name>/plan.md:

• What we're building and why
• Key decisions and trade-offs
• Files to create/modify
• Dependencies and ordering
• What "done" looks like
• The testing proof matrix for each functional slice: unit/contract,

functional, adversarial, E2E/VM, telemetry, and performance

• For Capsem release, VM, network, model, MCP, credential broker,

package-manager, doctor, benchmark, or security acceptance work, load

/ironbank and add an Ironbank entry to the proof matrix before coding

The plan is a living document. Update it as the sprint evolves -- crossed-out items, new discoveries, changed approach. The plan is evidence of thinking, not a contract.

2. Track

Create sprints/<sprint-name>/tracker.md as a checklist:

# Sprint: <name>

## Tasks
- [x] Task 1 -- description
- [x] Task 2 -- description
- [ ] Task 3 -- description
- [ ] Testing gate
- [ ] Changelog
- [ ] Commit

## Notes
- Discovery: found that X needs Y
- Changed approach: Z instead of W because...

## Coverage Ledger
- Unit/contract:
- Functional:
- Adversarial:
- E2E/VM:
- Telemetry:
- Performance:
- Missing/deferred:

Update the tracker as you go. Check items off. Add notes about surprises, blockers, and changed approaches. This is your scratchpad -- future you (or the next conversation) reads this to understand what happened.

For every functional milestone, keep the coverage ledger current. Do not mark a task complete with only implementation notes and a command list. Name the actual tests or manual VM checks that prove the feature, and name the missing categories honestly. A benchmark can prove performance, not functional correctness. A Rust unit suite can prove contracts, not the user-visible VM path.

For Ironbank slices, the focused verification must be the relevant

tests/ironbank/ case or a documented RED test that currently fails. Do not

mark Ironbank tests skip, skipif, slow, or optional; if a dependency is

missing, the product or harness is missing.

3. Build

Write code. Follow the project skills:

• /dev-debugging for bug investigation (reproduce first, diagnose, then fix)
• /dev-testing for TDD (write test, see it fail, implement, refactor)
• /ironbank for full black-box ledger acceptance; never close those gates

with Rust internals, status-only replay, row-exists checks, skip, or

slow

• /dev-rust-patterns for async/cross-compile patterns
• /dev-mitm-proxy, /dev-mcp for subsystem-specific guidance

Profile Source vs Generated Runtime Config

Keep profile/config ownership crisp:

• Read config/README.md and tests/README.md before changing config layout,

profile payloads, generated settings artifacts, or config test fixtures.

• Checked-in config/profiles/<id>/profile.toml is source contract, not a

scratchpad for local asset or payload hashes.

• Profile sibling files are source inputs. Do not add hash or size fields

to source profile.toml after changing build.sh, package files, rules,

MCP files, tips, or root seed manifests. Generated hashes belong in

target/config, asset manifests, OBOMs, or root manifests, never in the

checked-in profile source.

• Current asset URLs/hashes from assets/manifest.json are materialized into

target/config through the same capsem-admin/just rail used by CI and

release. Do not commit ad hoc target/config output.

• config/skills does not exist. Developer skills live in repository-level

skills/. User/profile skills, when implemented, are profile-owned payloads

with their own contract, not Codex development instructions.

• Any sprint that changes profile payloads must prove the profile-derived build rail, not a

manual TOML patch.

Names are part of the architecture contract. Prefer boring,

self-explanatory names that state what a thing is (mock_server,

profile_loader, security_rule) over origin-story names, lore names, or

names tied to the first caller (debug_upstream, benchmark-only labels,

temporary sprint names). If a developer cannot infer the contract from the

name before opening the file, rename it before the pattern spreads.

4. Commit at functional milestones

Do NOT commit after every file edit. Do NOT batch everything into one giant commit at the end. Commit when:

• A logical unit of work is complete and functional
• Tests pass for that unit
• The codebase is in a good state (not half-refactored)
• The tracker has an explicit coverage ledger for that milestone,

including missing/deferred functional, adversarial, E2E/VM, telemetry,

or performance coverage

Each commit should:

• Be self-contained (revertable without breaking things)
• Include its CHANGELOG.md entry
• Stage files explicitly (no git add -A)
• Use conventional messages: feat:, fix:, chore:, docs:

Bad: 20 tiny commits for each file touched. Also bad: 1 commit with 40 files after hours of work.

Good: 3-5 commits per sprint, each representing a meaningful milestone.

5. Changelog

Update CHANGELOG.md under ## [Unreleased] as part of each commit. Write from the user's perspective:

• Added: new capability
• Changed: modified behavior
• Fixed: bug fix
• Security: security improvement

Do not batch changelog entries at the end. Each commit carries its own entry.

6. Testing gate

Every sprint ends with testing. No exceptions.

just test                           # ALL tests: unit + integration + cross-compile + frontend + bench
just exec "capsem-doctor"            # VM smoke test

If the sprint touched telemetry:

python3 scripts/check_session.py                # Verify telemetry after a real session

If tests fail, fix them before considering the sprint done. See /dev-debugging for the methodology.

The testing gate must cover the story, not just the code that was easiest to test. For each shipped behavior, verify:

• Unit/contract tests for the smallest meaningful logic boundary
• Functional tests through the production-facing API
• Adversarial tests for malformed input, denials, timeouts, races, and leak prevention
• E2E/VM tests for the real user path when the behavior crosses a VM, CLI, MCP, service, telemetry, or network boundary
• Session DB or external-state checks when the behavior claims auditability
• Benchmarks only when performance is part of the claim
• Package-manager proof must be functional: apt, npm, uv, pip, node, and

profile package rails must prove the installed package runs and performs its

intended job, not merely that a package manager recorded it.

If one of those is missing, keep the sprint open or record the exact debt in the tracker with a follow-up task. Do not bury the gap in prose like "covered later"; make it visible.

7. Clean up

• Verify no debug prints, TODO comments, or temporary hacks remain
• Run /simplify if significant code was written

Sprint artifacts

sprints/<sprint-name>/
  plan.md           What we're building, key decisions
  tracker.md        Checklist + notes
  changelog.md      Draft changelog entries (optional, can go straight to CHANGELOG.md)

The sprints/ directory is git-tracked. Sprint plans and trackers are committed alongside the code they describe.

Meta sprints (sub-sprints)

Large efforts use a meta sprint with sub-sprints. The meta sprint has a MASTER.md that tracks overall status, and each sub-sprint gets its own file:

sprints/<meta-name>/
  MASTER.md                 Overall status table, phase groupings, just recipes
  T0-infrastructure.md      Sub-sprint 0
  T1-service-unit-tests.md  Sub-sprint 1
  T2-process-unit-tests.md  Sub-sprint 2
  ...
  implementation-tasks.md   What code must change for tests to pass (optional)
  tracker.md                Active execution tracker (current sub-sprint progress)

MASTER.md is the entry point. It contains:

• A status table with every sub-sprint, its status (Done / In Progress / Not Started), test count, and dependencies
• Phase groupings (Foundation, Integration, E2E, etc.)
• Relevant just recipes

When executing a meta sprint, create a tracker.md for the active work. Update MASTER.md status as sub-sprints complete.

Anti-patterns

• No plan: jumping straight to code leads to rework and wrong abstractions
• Commit per file: noise in git history, impossible to revert cleanly
• One mega commit: can't bisect, can't review, can't cherry-pick
• Skip testing: "I'll test later" means "I'll ship bugs now"
• Stale tracker: if the tracker doesn't match reality, it's useless
• Benchmark-as-proof: performance numbers do not prove the feature is correct
• Silent coverage debt: missing E2E, functional, or adversarial tests must be named before a milestone can be called done
• Ironbank theater: status-code-only replay, row-exists checks,

parser-only proof, Rust-internal expectations, public-network fixtures,

skip, skipif, or slow cannot close release-critical VM/security work