Josh Knapp
7840bddbb4
Pulls in 15 upstream commits since the April 3 bundling snapshot
(msieurthenardier/mission-control). Notable changes:
- agentic-workflow rewritten as the "fast" variant: per-leg design and
implement, single review and commit across the whole flight
- New Skill-Project Boundary section: skills no longer read or write
project-owned artifacts by literal heading
- routine-maintenance scoped to post-mission only; adds state-machine
reachability and cache freshness audits
- Test metrics capture threaded through debrief, maintenance, and flight
- Crew prompts no longer carry skill-required instructions; SKILL.md is
the protocol
- Worktree git strategy removed; standardized on {target-project}
- Jira artifact template removed upstream
Local URL correction in init-project/README.md preserved
(anthropics/flight-control -> msieurthenardier/mission-control).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
122 lines
8.0 KiB
Markdown
122 lines
8.0 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Invocation Context
|
||
|
||
You may be invoked by:
|
||
- **A human** — Interactive session, ask questions freely
|
||
- **An LLM orchestrator** — Run `/agentic-workflow` to drive multi-agent flight execution
|
||
|
||
When orchestrated, you are the **Flight Director** — responsible for driving execution, coordinating agents, and making go/no-go decisions. Emit signals like `[HANDOFF:review-needed]` and `[COMPLETE:leg]` at appropriate points. The orchestrator monitors your output for these markers.
|
||
|
||
**When a human says a leg is ready to implement**, invoke `/agentic-workflow`. Do not read the leg spec, do not plan execution steps, do not execute commands directly. You become the orchestrator by loading the skill.
|
||
|
||
### Loading Skills in Non-Interactive Contexts
|
||
|
||
**The Skill tool is ONLY available in interactive human sessions.** If you are a spawned agent, running via `claude -p`, or inside a container/SDK — you do NOT have the Skill tool. Do not attempt to call it.
|
||
|
||
To execute a skill, read its SKILL.md file directly and follow the workflow:
|
||
|
||
```
|
||
Read .claude/skills/{skill-name}/SKILL.md and execute the workflow described there.
|
||
```
|
||
|
||
**All Flight Control skills** (listed in the table below) **live in this repository** (mission-control), under `.claude/skills/`. The Flight Director runs from the mission-control directory, so relative `.claude/skills/` paths in skill docs resolve here. Target projects may have their own unrelated skills in their own `.claude/skills/` directories — those are separate.
|
||
|
||
## First-Contact Check
|
||
|
||
If `projects.md` does not exist in this repository, suggest running `/init-mission-control` to set up the projects registry before proceeding with any other skills.
|
||
|
||
## Project Overview
|
||
|
||
Flight Control is an AI-first software development lifecycle methodology using aviation metaphors. It organizes work into three hierarchical levels:
|
||
|
||
- **Missions** (human-optimized) — Define outcomes in human terms, days-to-weeks scope
|
||
- **Flights** (balanced) — Technical specifications with pre/in/post-flight checklists, hours-to-days scope
|
||
- **Legs** (AI-optimized) — Structured implementation steps with explicit acceptance criteria, minutes-to-hours scope
|
||
|
||
This repository contains the methodology documentation and Claude Code skills for interactive planning.
|
||
|
||
## Claude Code Skills
|
||
|
||
Eleven skills automate the planning, execution, debrief, and oversight workflow:
|
||
|
||
| Skill | Purpose |
|
||
|-------|---------|
|
||
| `/init-mission-control` | Onboard to Mission Control (set up `projects.md` registry) |
|
||
| `/init-project` | Initialize a project for Flight Control (creates `.flightops/` directory) |
|
||
| `/mission` | Create outcome-driven missions through research and interview |
|
||
| `/flight` | Create technical flight specs from missions |
|
||
| `/leg` | Generate implementation guidance for LLM execution |
|
||
| `/agentic-workflow` | Drive multi-agent flight execution (design per leg, batch implement, single review and commit) |
|
||
| `/flight-debrief` | Post-flight analysis for continuous improvement |
|
||
| `/mission-debrief` | Post-mission retrospective for outcomes assessment |
|
||
| `/routine-maintenance` | Post-mission codebase health assessment and maintenance recommendation |
|
||
| `/preflight-check` | Verify all projects have current methodology files and crew definitions |
|
||
| `/daily-briefing` | Cross-project status report with health assessment and methodology insights |
|
||
|
||
Run `/init-project` before using the other skills on a new project to create the flight operations reference directory and configure the artifact system.
|
||
|
||
**Artifact Systems:** Each project defines how artifacts are stored in `.flightops/ARTIFACTS.md`. Skills read this configuration and adapt their output accordingly.
|
||
|
||
**IMPORTANT: Planning skills produce documentation only.** `/init-project`, `/mission`, `/flight`, `/leg`, `/flight-debrief`, `/mission-debrief`, and `/routine-maintenance` must:
|
||
- **NEVER implement code changes** — only create/update artifacts
|
||
- **NEVER modify source files** in the target project (no `.rs`, `.ts`, `.tsx`, `.json`, etc.)
|
||
|
||
`/agentic-workflow` orchestrates implementation by spawning separate agents that execute code changes in the target project. The orchestrator itself never modifies source files directly.
|
||
|
||
> **Phase gates require confirmation.** Missions must be fully agreed before designing
|
||
> flights. Flights must be fully agreed before designing legs. Never skip ahead — get
|
||
> explicit user confirmation at each transition.
|
||
|
||
## Projects Registry
|
||
|
||
The `projects.md` file in this repository catalogs all active projects on this device. When using skills:
|
||
|
||
1. **Read `projects.md` first** to find the target project's path, remote, and description
|
||
2. **Read `.flightops/ARTIFACTS.md`** in the target project to determine artifact locations
|
||
3. **Create all artifacts in the target project** — not in mission-control
|
||
|
||
The registry provides:
|
||
- Project slug and description
|
||
- Filesystem path (e.g., `~/projects/my-app`)
|
||
- Git remote
|
||
- Optional stack and status information
|
||
|
||
## Lifecycle States
|
||
|
||
- **Missions**: `planning` → `active` → `completed` (or `aborted`)
|
||
- **Flights**: `planning` → `ready` → `in-flight` → `landed` → `completed` (or `aborted`)
|
||
- **Legs**: `planning` → `ready` → `in-flight` → `landed` → `completed` (or `aborted`)
|
||
|
||
## Skill–Project Boundary
|
||
|
||
Mission Control skills run in projects whose owners can customize `.flightops/ARTIFACTS.md` and `.flightops/agent-crews/*.md` freely. Skills must not couple to project-owned shape:
|
||
|
||
- **Do not read project-owned artifacts by section heading.** When a skill needs to extract information from a prior debrief, maintenance report, or other project-owned artifact, frame the instruction by intent — what the agent is looking for — and let the agent locate it within whatever structure the project uses. Reading by literal heading name (e.g. `## Action Items`, `## Test Suite Timing`) breaks silently the moment a project owner renames or removes that section.
|
||
- **Do not write into project-owned artifacts at named anchors.** When a skill inserts content into a project artifact, describe the destination semantically ("in the section the project uses for X") rather than by literal heading. If the skill is appending a new section, suggest a heading without prescribing it as a contract.
|
||
- **Do not rely on crew prompt files to carry skill-required instructions.** The Flight Director must issue per-spawn instructions directly from the SKILL.md, even when the crew file also contains an overlapping prompt. Crew files are project-modifiable scaffolding; SKILL.md is the protocol.
|
||
|
||
See `docs/artifacts-md-ambiguities.md` for the full review of how the current ARTIFACTS.md template muddles this boundary.
|
||
|
||
## Project Information Stays in Project Artifacts
|
||
|
||
**Never store project-specific information in Claude Code memories** — not in mission-control's memory directory, not in any project's memory directory. Project-specific issues, bugs, technical debt, design gaps, known issues, and lessons learned belong exclusively in the project's own Flight Control artifacts:
|
||
|
||
- **Flight logs** — runtime decisions, deviations, anomalies
|
||
- **Flight debriefs** — post-flight analysis, recommendations, action items
|
||
- **Mission known issues** — cross-flight concerns discovered during execution
|
||
- **Design decision sections** — in flight and mission artifacts
|
||
|
||
Mission-control is a neutral methodology tool. Its memory (if used at all) is reserved for methodology preferences, user collaboration preferences, and cross-cutting tooling notes — never for project-specific content.
|
||
|
||
## Public Repository
|
||
|
||
This is a public repository. Keep all committed content anonymized:
|
||
|
||
- **No personal paths** — Use generic examples like `~/projects/my-app`, not actual home directories
|
||
- **No usernames** — Use placeholders like `username` in examples
|
||
- **No project-specific details** — Keep examples generic
|
||
- `projects.md` is gitignored for this reason — it contains local paths and is not committed
|