CyberCoveLLC/Triple-C
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

Bundle mission-control into Triple-C instead of cloning from GitHub
All checks were successful
Build App / compute-version (push) Successful in 2s
Details
Build App / build-macos (push) Successful in 2m47s
Details
Build Container / build-container (push) Successful in 9m0s
Details
Build App / build-linux (push) Successful in 4m41s
Details
Build App / build-windows (push) Successful in 5m33s
Details
Build App / create-tag (push) Successful in 3s
Details
Build App / sync-to-github (push) Successful in 10s
Details

Browse Source 
The mission-control (Flight Control) project is being closed upstream.
This embeds the project files directly in the repo under container/mission-control/,
bakes them into the Docker image at /opt/mission-control, and copies them into place
at container startup instead of git cloning from GitHub.

Also adds missing osc52-clipboard, audio-shim, and triple-c-sso-refresh to the
programmatic Docker build context in image.rs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Josh Knapp
2026-04-03 09:09:15 -07:00
parent 57a7cee544
commit 2dffef0767
43 changed files with 7212 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
container/mission-control/.claude/skills/init-project/FLIGHT_OPERATIONS.md Normal file
View File

@@ -0,0 +1,182 @@
# Flight Operations Quick Reference
> For full methodology docs, see [mission-control](https://github.com/msieurthenardier/mission-control)
## Before You Start
**Read these files in order:**
1. `.flightops/ARTIFACTS.md` — Where and how artifacts are stored (project-specific)
2. The **flight log** for your active flight — Ground truth for what happened
3. The **leg artifact** you're implementing — Your acceptance criteria
---
## Project Crew & Phases
Each phase of the Flight Control workflow has a crew definition in `.flightops/agent-crews/`:
| Crew | Purpose |
|------|---------|
| `mission-design.md` | Crew for `/mission` (e.g., Architect validates viability) |
| `flight-design.md` | Crew for `/flight` (e.g., Architect reviews spec) |
| `leg-execution.md` | Crew for `/agentic-workflow` (e.g., Developer + Reviewer) |
| `flight-debrief.md` | Crew for `/flight-debrief` (e.g., Developer provides perspective) |
| `mission-debrief.md` | Crew for `/mission-debrief` (e.g., Architect provides perspective) |
Crew files define: roles, models, interaction protocols, prompts, and signals. Customize these to change your project's agent configuration.
---
## Multi-Agent Workflow
Legs must be implemented by a **separate Developer instance** and reviewed by a **separate Reviewer instance** (or whatever crew is defined in `leg-execution.md`). Mission Control designs legs and orchestrates — it does NOT implement code directly.
The Reviewer has no knowledge of the Developer's reasoning — only the resulting changes. This separation provides objective code review. Use the `/agentic-workflow` skill in mission-control to drive this cycle.
---
## ⚠️ Leg Completion Checklist (MANDATORY)
**You MUST complete ALL of these before emitting `[COMPLETE:leg]`:**
| Step | Action |
|------|--------|
| 1 | All acceptance criteria verified |
| 2 | Tests passing |
| 3 | **Update flight log** — Add leg progress entry (see below) |
| 4 | **Mark leg completed** — Update leg status to `completed` |
| 5 | **Update flight** — Check off the leg in flight artifact |
| 6 | **Commit/save with all artifact updates** |
**Flight log entry MUST include:**
- Leg status, started date, completed date
- Changes Made (what was implemented)
- Verification (how acceptance criteria were confirmed)
- Any decisions, deviations, or anomalies
Refer to `.flightops/ARTIFACTS.md` for exact locations and formats.
---
## Workflow Signals
Emit at the end of your response, on its own line:
| Signal | When |
|--------|------|
| `[HANDOFF:review-needed]` | Artifact changes ready for validation |
| `[HANDOFF:confirmed]` | Review complete, no issues |
| `[BLOCKED:reason]` | Cannot proceed |
| `[COMPLETE:leg]` | Leg done AND checklist complete |
---
## Implementing a Leg
### Pre-Implementation
1. Read mission, flight, and leg artifacts
2. Read flight log for context from prior legs
3. Verify leg accuracy against existing code
4. **Update leg status** to `in-flight`
5. Present summary and get approval before proceeding
### Implementation
5. Implement to acceptance criteria
6. Run tests with a timeout — use the test runner's timeout flag (e.g., `--timeout`,
`--test-timeout`, `-timeout`) so hanging tests fail fast instead of stalling.
If a test hangs, kill it, isolate the hanging test, and fix the root cause before
continuing. Log hanging tests and their resolution in the flight log.
7. Run code review, fix Critical/Major issues
8. Re-review until clean
### Post-Implementation
9. Propagate changes (project docs, flight artifacts if scope changed)
10. **Complete the Leg Completion Checklist above**
11. Signal `[COMPLETE:leg]`
---
## Just-in-Time Planning
Flights and legs are created one at a time, not upfront.
| Reviewing... | Should exist | Should NOT exist yet |
|--------------|--------------|----------------------|
| Mission | Mission artifact | Flight artifacts (only listed) |
| Flight | Flight artifact | Leg artifacts (only listed) |
| Leg | Leg artifact | Ready to implement |
Listed flights/legs are **tentative suggestions** that evolve based on discoveries.
---
## Reviewing Artifacts
When reviewing a mission, flight, or leg:
1. Read the artifact thoroughly
2. Validate against project goals and existing code
3. Check for ambiguities or missing details
4. Make changes directly if needed
5. Describe any changes made
6. Signal `[HANDOFF:confirmed]` if no issues, or describe changes for validation
---
## Code Review Gate
```
Implement → Test → Review → Fix → Re-review → Complete
```
| Severity | Action |
|----------|--------|
| Critical | Must fix |
| Major | Must fix |
| Minor | Fix if safe, else defer |
Deferred issues go in the flight log.
---
## ⚠️ Flight Completion Checklist (MANDATORY)
**When you complete the FINAL leg of a flight, also complete these steps:**
| Step | Action |
|------|--------|
| 1 | Complete all items in the Leg Completion Checklist above |
| 2 | **Update flight log** — Add flight completion entry with summary |
| 3 | **Update flight status** — Set `**Status**: landed` in flight.md |
| 4 | **Update mission** — Check off this flight in mission.md |
| 5 | **Verify all legs** — Confirm all legs show `completed` status |
| 6 | **Update project docs** — Ensure CLAUDE.md, README, and other docs reflect any new commands, endpoints, configuration, or APIs introduced during the flight |
| 7 | Signal `[COMPLETE:leg]` (the orchestrator will trigger Phase 4) |
The orchestrator will then:
- Mark the PR ready for human review
The flight debrief is a separate step run via `/flight-debrief`, which transitions the flight from `landed` to `completed`.
---
## Database Schema Changes
When a flight modifies database schemas:
1. **Include migration steps in the leg** — schema changes need explicit CREATE/ALTER statements or migration commands
2. **Verify migrations run** — acceptance criteria must include confirming the migration executed successfully against the live database
3. **Update SCHEMA docs** — if the project maintains a SCHEMA reference, update it in the same leg that creates the migration
4. **Test against real DB** — unit tests with mocks are not sufficient for schema changes; verify against the actual database
A table defined in SCHEMA but never created via migration is a gap — treat schema documentation and migration execution as a single atomic operation.
---
## Key Principles
1. **Flight log is ground truth** — Read it first, update it always
2. **Never modify in-flight legs** — Create new ones instead
3. **Binary acceptance criteria** — Met or not met
4. **Log everything** — Decisions, deviations, anomalies
5. **Signal clearly** — End of response, own line

29
container/mission-control/.claude/skills/init-project/README.md Normal file
View File

@@ -0,0 +1,29 @@
# Flight Operations
This directory contains reference materials for the [Flight Control](https://github.com/anthropics/flight-control) development methodology.
## Contents
- **FLIGHT_OPERATIONS.md** — Quick reference for implementing missions, flights, and legs
- **ARTIFACTS.md** — Project-specific configuration for how artifacts are stored
- **agent-crews/** — Project crew definitions for each phase (who Mission Control works with)
## For AI Agents
When working on this project with Flight Control:
1. Read `ARTIFACTS.md` to understand how this project stores missions, flights, and legs
2. Read `FLIGHT_OPERATIONS.md` for the implementation workflow
3. Read the relevant `agent-crews/*.md` file for crew definitions and prompts
4. Check the artifact locations defined in `ARTIFACTS.md` for active work
5. Follow the code review gate before marking any leg complete
6. Update flight-log after each leg (location depends on artifact system)
## Sync Behavior
| File | Synced? | Notes |
|------|---------|-------|
| README.md | Yes | Updated via `/init-project` |
| FLIGHT_OPERATIONS.md | Yes | Updated via `/init-project` |
| ARTIFACTS.md | No | Project-specific, customize freely |
| agent-crews/*.md | No | Project-specific, customize freely |

215
container/mission-control/.claude/skills/init-project/SKILL.md Normal file
View File

@@ -0,0 +1,215 @@
---
name: init-project
description: Initialize a project for Flight Control. Creates .flightops directory with methodology reference and artifact configuration. Run before using other Flight Control skills on a new project.
---
# Project Initialization
Prepare a project for Flight Control by creating the `.flightops/` directory with methodology references and artifact configuration.
## When to Use
Run `/init-project` when:
- Starting to use Flight Control on a new project
- You suspect the .flightops reference may be outdated
- Another skill indicates the reference needs to be synced
## Workflow
### 1. Identify Target Project
1. **Read `projects.md`** to find the project's path, remote, and description
2. If the project isn't listed, ask the user for:
- Project name/slug
- Filesystem path
- Brief description
3. Optionally offer to add the project to `projects.md`
### 2. Check and Apply Migrations
Check for legacy directory layouts and offer to migrate them.
1. **Read `migrations.md`** from the skill directory (`${SKILL_DIR}/migrations.md`)
2. **Run detection checks** for each migration in order (001, 002, ...)
3. **If no migrations are needed**, proceed silently to the next step
4. **If any migrations are needed**, present a summary to the user:
> "Detected legacy directory layout in {project}. The following migrations are available:"
>
> - _Each applicable migration's user message_
>
> "Apply these migrations?"
5. **On confirmation**, apply the actions for each applicable migration in order
6. **On decline**, warn the user that some skills may not work correctly with the old layout, but continue using whatever directory structure exists
### 3. Check Sync Status
Run the hash comparison script to determine sync status:
```bash
bash "${SKILL_DIR}/check-sync.sh" \
"${SKILL_DIR}" \
"{target-project}/.flightops"
```
The script outputs one of:
- `missing` - Directory doesn't exist in target project
- `outdated` - Directory exists but files differ from source
- `current` - All files are up-to-date
### 4. Prompt and Sync Methodology Files
Based on the status:
**If `missing`**:
> "Flight operations directory not found. Create `{project}/.flightops/` with methodology references?"
**If `outdated`**:
> "Flight operations references in {project} are outdated. Update?"
**If `current`**:
> "Flight operations references are up-to-date in {project}."
If the user confirms, create/update the directory:
```bash
mkdir -p "{target-project}/.flightops"
cp "${SKILL_DIR}/FLIGHT_OPERATIONS.md" "{target-project}/.flightops/"
cp "${SKILL_DIR}/README.md" "{target-project}/.flightops/"
```
### 5. Configure Artifact System (New Projects Only)
**Only if ARTIFACTS.md doesn't exist**, ask the user to select an artifact system:
> "How should mission, flight, and leg artifacts be stored?"
Available templates:
- **files** — Markdown files in the repository (`templates/ARTIFACTS-files.md`)
- **jira** — Jira issues: Epics, Stories, Sub-tasks (`templates/ARTIFACTS-jira.md`)
#### 5a. Check for Setup Questions
After the user selects a template, read the template file and check if it contains a `## Setup Questions` section with a table of questions.
If setup questions exist:
1. Parse the questions from the table (first column contains the questions)
2. Ask the user each question interactively
3. Replace the placeholder answers in the table with the user's responses
#### 5b. Copy and Populate Template
Copy the selected template, with answers populated if setup questions were asked:
```bash
cp "${SKILL_DIR}/templates/ARTIFACTS-{selection}.md" \
"{target-project}/.flightops/ARTIFACTS.md"
```
If setup questions were answered, update the ARTIFACTS.md file to replace the placeholder answers with the user's responses.
**If ARTIFACTS.md already exists**, do not modify it — it's project-specific and may have been customized.
### 6. Configure Project Crew
Set up phase-specific crew definitions that control how Mission Control interacts with project-side agents.
1. **Check if `.flightops/agent-crews/` exists**
**If missing** (first run):
- Copy all defaults from `${SKILL_DIR}/defaults/agent-crews/` to `{target-project}/.flightops/agent-crews/`
- Brief the user:
> "Default crew has been set up for all phases. Your agent crews define who Mission Control (Flight Director) works with during each phase — which agents exist, their roles, models, and prompts."
- Ask about customization:
> "Want to customize any agent crew? (Most projects work fine with defaults)"
- If yes: ask which crew → show current definitions → walk through changes (add/remove/modify roles, adjust prompts, change interaction protocol)
- If no: proceed with defaults
**If exists** (re-run):
- Copy any missing crew files from defaults (new crews added to the methodology)
- Ask the user:
> "Agent crew files already exist. Default crew definitions may have been updated since your project was initialized. Want to review and update any crew files to the latest defaults?"
- If yes: for each file, show what changed between their version and the current default, ask whether to overwrite or keep their version
- If no: leave all existing files untouched
### 7. Update CLAUDE.md
Check if the project's `CLAUDE.md` file references the flight operations directory:
1. **If CLAUDE.md doesn't exist**, create it with a Flight Operations section
2. **If CLAUDE.md exists but lacks a Flight Operations section**, append one
3. **If CLAUDE.md already has a Flight Operations section**, leave it unchanged
#### 7a. Fix Stale Path References
If migrations were applied in Step 2, scan the project's `CLAUDE.md` for stale path references within the Flight Operations section and fix them:
- Replace `.flight-ops/` → `.flightops/`
- Replace `phases/` → `agent-crews/` (only within Flight Operations context)
This ensures the CLAUDE.md instructions point to the correct post-migration paths.
Add this section:
```markdown
## Flight Operations
This project uses [Flight Control](https://github.com/msieurthenardier/mission-control).
**Before any mission/flight/leg work, read these files in order:**
1. `.flightops/README.md` — What the flightops directory contains
2. `.flightops/FLIGHT_OPERATIONS.md` — **The workflow you MUST follow**
3. `.flightops/ARTIFACTS.md` — Where all artifacts are stored
4. `.flightops/agent-crews/` — Project crew definitions for each phase (read the relevant crew file)
```
### 8. Post-Sync Instructions
After creating or updating the directory, inform the user:
> "If you have Claude Code running in {project}, restart it to pick up the new flight operations references."
This ensures Claude Code loads the new files into its context when working in the target project.
## Output
This skill creates/updates the following at project root:
```
{project}/
├── CLAUDE.md # Updated with Flight Operations section
└── .flightops/ # Hidden directory for Flight Control
├── README.md # Explains the directory purpose
├── FLIGHT_OPERATIONS.md # Quick reference for implementation (synced)
├── ARTIFACTS.md # Artifact system configuration (project-specific)
└── agent-crews/ # Project crew definitions (project-specific)
├── mission-design.md
├── flight-design.md
├── leg-execution.md
├── flight-debrief.md
├── mission-debrief.md
└── routine-maintenance.md
```
## File Sync Behavior
| File | Synced on update? | Notes |
|------|-------------------|-------|
| CLAUDE.md | Append only | Adds Flight Operations section if missing |
| README.md | Yes | Methodology reference |
| FLIGHT_OPERATIONS.md | Yes | Methodology reference |
| ARTIFACTS.md | No | Created once from template, then project-specific |
| agent-crews/*.md | Ask on re-run | Created from defaults; on re-run, user can choose to update to latest defaults |
## Guidelines
### Don't Over-Prompt
If everything is `current`, just inform the user briefly and move on. No confirmation needed.
### Respect ARTIFACTS.md
Never overwrite ARTIFACTS.md — it may contain project-specific customizations. Only create it if missing.
### Keep It Quick
This is a setup step, not the main work. Complete it efficiently so the user can proceed to their actual task.

119
container/mission-control/.claude/skills/init-project/check-sync.sh Executable file
View File

@@ -0,0 +1,119 @@
#!/bin/bash
# check-sync.sh - Compare .flightops directory between source and target
#
# Usage: check-sync.sh <source-dir> <target-dir>
#
# Outputs:
# missing - Target directory doesn't exist (neither .flightops/ nor .flight-ops/)
# outdated - Target exists but one or more files differ from source
# current - All files match source
#
# Additional output lines:
# agent-crews:{missing|empty|present} - Crew directory status
# crew-missing:{filename} - Default crew file not found in project (repeats per file)
# legacy-layout:flight-ops - .flight-ops/ detected (old name)
# legacy-layout:phases - phases/ detected (old name)
#
# Note: Only checks synced files (README.md, FLIGHT_OPERATIONS.md).
# ARTIFACTS.md and agent-crews/ are project-specific and not synced.
set -e
SOURCE_DIR="$1"
TARGET_DIR="$2"
if [[ -z "$SOURCE_DIR" || -z "$TARGET_DIR" ]]; then
echo "Usage: check-sync.sh <source-dir> <target-dir>" >&2
exit 1
fi
if [[ ! -d "$SOURCE_DIR" ]]; then
echo "Error: Source directory not found: $SOURCE_DIR" >&2
exit 1
fi
# Resolve the actual target directory, falling back to legacy name
EFFECTIVE_TARGET="$TARGET_DIR"
LEGACY_FLIGHT_OPS=false
if [[ ! -d "$TARGET_DIR" ]]; then
# Derive the legacy path: replace trailing .flightops with .flight-ops
LEGACY_DIR="${TARGET_DIR%/.flightops}/.flight-ops"
if [[ "$LEGACY_DIR" != "$TARGET_DIR" && -d "$LEGACY_DIR" ]]; then
EFFECTIVE_TARGET="$LEGACY_DIR"
LEGACY_FLIGHT_OPS=true
else
echo "missing"
exit 0
fi
fi
# Compare each file in source directory
FILES_TO_CHECK=("FLIGHT_OPERATIONS.md" "README.md")
ALL_CURRENT=true
for FILE in "${FILES_TO_CHECK[@]}"; do
SOURCE_FILE="$SOURCE_DIR/$FILE"
TARGET_FILE="$EFFECTIVE_TARGET/$FILE"
if [[ ! -f "$SOURCE_FILE" ]]; then
continue
fi
if [[ ! -f "$TARGET_FILE" ]]; then
ALL_CURRENT=false
break
fi
SOURCE_HASH=$(sha256sum "$SOURCE_FILE" | cut -d' ' -f1)
TARGET_HASH=$(sha256sum "$TARGET_FILE" | cut -d' ' -f1)
if [[ "$SOURCE_HASH" != "$TARGET_HASH" ]]; then
ALL_CURRENT=false
break
fi
done
if $ALL_CURRENT; then
echo "current"
else
echo "outdated"
fi
# Report on agent-crews directory existence, checking both current and legacy names
CREW_DIR=""
LEGACY_PHASES=false
if [[ -d "$EFFECTIVE_TARGET/agent-crews" ]]; then
CREW_DIR="$EFFECTIVE_TARGET/agent-crews"
elif [[ -d "$EFFECTIVE_TARGET/phases" ]]; then
CREW_DIR="$EFFECTIVE_TARGET/phases"
LEGACY_PHASES=true
fi
if [[ -z "$CREW_DIR" ]]; then
echo "agent-crews:missing"
elif [[ -z "$(ls -A "$CREW_DIR" 2>/dev/null)" ]]; then
echo "agent-crews:empty"
else
echo "agent-crews:present"
# Check for missing crew files (new skills added since init)
DEFAULT_CREWS_DIR="$SOURCE_DIR/defaults/agent-crews"
if [[ -d "$DEFAULT_CREWS_DIR" ]]; then
for DEFAULT_FILE in "$DEFAULT_CREWS_DIR"/*.md; do
BASENAME=$(basename "$DEFAULT_FILE")
if [[ ! -f "$CREW_DIR/$BASENAME" ]]; then
echo "crew-missing:$BASENAME"
fi
done
fi
fi
# Report legacy layout detection
if $LEGACY_FLIGHT_OPS; then
echo "legacy-layout:flight-ops"
fi
if $LEGACY_PHASES; then
echo "legacy-layout:phases"
fi

126
container/mission-control/.claude/skills/init-project/defaults/agent-crews/flight-debrief.md Normal file
View File

@@ -0,0 +1,126 @@
# Flight Debrief — Project Crew
Crew definitions for post-flight analysis. The Flight Director interviews the
human and project-side agents to capture both execution and design perspectives.
## Crew
### Developer
- **Context**: {project}/
- **Model**: Sonnet
- **Role**: Provides developer perspective on flight execution. Reviews what was
built, identifies technical debt introduced, evaluates implementation quality,
and surfaces issues that flight logs may not capture.
- **Actions**: debrief-interview
### Architect
- **Context**: {project}/
- **Model**: Sonnet
- **Role**: Closes the design feedback loop. Evaluates whether the design decisions
made during flight planning held up in practice. Reviews architectural impact of
what was built and whether the approach should be adjusted for future flights.
- **Actions**: debrief-design-review
## Interaction Protocol
### Developer Interview
1. Flight Director loads flight context (mission, flight, legs, log, actual code)
2. Flight Director spawns **Developer** to review implementation and provide feedback
3. Developer examines code changes, test coverage, patterns used, debt introduced
4. Developer provides structured debrief input
### Architect Interview
1. Flight Director spawns **Architect** to review whether design decisions held up
2. Architect compares flight-design spec against actual implementation
3. Architect evaluates architectural impact and provides feedback for future flights
### Human Interview
1. Flight Director interviews human with targeted questions based on flight log
2. Keep lightweight — 2-3 questions max
### Synthesis
1. Flight Director synthesizes Developer input + Architect input + human input + document analysis
2. Generates debrief artifact
## Template Variables
The Flight Director substitutes these variables in prompts at runtime:
| Variable | Description |
|----------|-------------|
| `{project-slug}` | Project identifier from projects.md |
| `{flight-number}` | Current flight number |
| `{flight-artifact-path}` | Path to the flight artifact file |
## Prompts
### Developer: Debrief Interview
```
role: developer
phase: flight-debrief
project: {project-slug}
flight: {flight-number}
action: debrief-interview
Review the implementation produced during this flight. Examine the code changes,
test coverage, and architectural decisions made.
Provide structured input for the debrief:
**Implementation Quality**:
- Does the code follow project conventions?
- Are there patterns that should be documented?
- What technical debt was introduced?
**Leg Spec Accuracy**:
- Were leg specs clear and sufficient for implementation?
- What was missing or misleading?
- Were acceptance criteria verifiable?
**Testing Assessment**:
- Is test coverage adequate?
- Are there untested edge cases?
- Do tests meaningfully validate behavior?
**Recommendations**:
- What should future flights in this area account for?
- Are there refactoring opportunities?
- What documentation is missing?
```
### Architect: Debrief Design Review
```
role: architect
phase: flight-debrief
project: {project-slug}
flight: {flight-number}
action: debrief-design-review
Read the flight artifact at {flight-artifact-path}. Compare the design decisions,
technical approach, and leg breakdown that were planned against what was actually
implemented.
Provide structured input for the debrief:
**Design Decisions Assessment**:
- Which design decisions held up well in practice?
- Which decisions had to be revised during implementation? Why?
- Were there decisions that should have been made differently?
**Architectural Impact**:
- Did the implementation maintain or improve the system's architecture?
- Were there unplanned structural changes? Are they sound?
- Did the approach create any architectural debt?
**Flight Design Accuracy**:
- Was the technical approach feasible as specified?
- Were prerequisites correctly identified?
- Was the leg breakdown appropriate for the actual work?
**Forward-Looking**:
- What should future flight designs in this area account for?
- Are there architectural patterns that emerged worth standardizing?
- What design assumptions should be revisited?
```

72
container/mission-control/.claude/skills/init-project/defaults/agent-crews/flight-design.md Normal file
View File

@@ -0,0 +1,72 @@
# Flight Design — Project Crew
Crew definitions for flight specification. The Flight Director designs the
technical spec and uses project-side agents to validate against the real codebase.
## Crew
### Architect
- **Context**: {project}/
- **Model**: Sonnet
- **Role**: Reviews flight specs for technical soundness. Validates design
decisions, prerequisites, technical approach, and leg breakdown against
architecture best practices and actual codebase state. Ensures the flight
is buildable and well-structured.
- **Actions**: review-flight-design
## Interaction Protocol
### Design Review
1. Flight Director creates flight spec and interviews human
2. Flight Director spawns **Architect** to review against codebase
3. Architect evaluates design decisions, prerequisites, approach, leg breakdown
4. Flight Director incorporates feedback
5. Max 2 review cycles — escalate to human if unresolved
## Template Variables
The Flight Director substitutes these variables in prompts at runtime:
| Variable | Description |
|----------|-------------|
| `{project-slug}` | Project identifier from projects.md |
| `{flight-number}` | Current flight number |
| `{flight-artifact-path}` | Path to the flight artifact file |
## Prompts
### Architect: Review Flight Design
```
role: architect
phase: flight-design-review
project: {project-slug}
flight: {flight-number}
action: review-flight-design
Read the flight artifact at {flight-artifact-path}. Cross-reference its design
decisions, prerequisites, technical approach, and leg breakdown against the actual
codebase state and architecture best practices.
Evaluate:
1. Design decisions — are they sound given the real codebase and architecture?
2. Prerequisites — are they accurate? Is anything missing or already done?
3. Technical approach — is it feasible? Does it follow existing patterns?
4. Leg breakdown — are legs well-scoped, properly ordered, with correct dependencies?
5. Codebase state — does the spec account for current working tree, existing tooling,
and conventions that might affect implementation?
6. Architecture — does the approach maintain or improve system structure?
Provide structured output:
**Overall assessment**: approve | approve with changes | needs rework
**Issues** (ranked by severity):
- [high/medium/low] Description — recommended fix
**Suggestions** (non-blocking improvements):
- Description
**Questions** (for the designer to clarify):
- Question
```

216
container/mission-control/.claude/skills/init-project/defaults/agent-crews/leg-execution.md Normal file
View File

@@ -0,0 +1,216 @@
# Leg Execution — Project Crew
Crew definitions and interaction protocol for implementing flight legs.
The Flight Director (Mission Control) orchestrates this phase using the
/agentic-workflow skill.
## Crew
### Developer
- **Context**: {working-directory}/
- **Model**: Sonnet
- **Role**: Implements code changes. Also performs design reviews against real
codebase to validate leg specs before implementation.
- **Actions**: implement, fix-review-issues, commit, review-leg-design
### Reviewer
- **Context**: {working-directory}/
- **Model**: Sonnet (NEVER Opus)
- **Role**: Reviews code changes for quality, correctness, and criteria compliance.
Has NO knowledge of Developer's reasoning — only sees resulting changes.
- **Actions**: review
### Accessibility Reviewer (optional)
- **Context**: {working-directory}/
- **Model**: Sonnet
- **Enabled**: false
- **Role**: Reviews UI changes for accessibility compliance. Evaluates against
WCAG 2.1 AA standards, screen reader compatibility, keyboard navigation,
color contrast, ARIA usage, and semantic HTML. Only spawn when the leg
involves user-facing interface changes.
- **Actions**: review-accessibility
## Separation Rules
- Developer and Reviewer load the target project's CLAUDE.md and conventions
- Reviewer has NO knowledge of Developer's reasoning — only resulting changes
- Each agent instance gets fresh context (no carryover between legs)
**Note:** Handoff signals (`[HANDOFF:review-needed]`, `[HANDOFF:confirmed]`, `[BLOCKED:reason]`, `[COMPLETE:leg]`) are defined by the Flight Control methodology in the agentic-workflow skill, not in this file. Do not modify signal names here — they must match what the Flight Director expects.
## Interaction Protocol
### Design Review
1. Flight Director spawns **Developer** for design review
2. Developer reviews leg against codebase, provides structured assessment
3. Flight Director incorporates feedback
4. Max 2 review cycles — escalate to human if unresolved
### Implementation
1. Flight Director spawns **Developer** to implement
2. Developer implements to acceptance criteria, updates flight log
3. Developer signals [HANDOFF:review-needed] — does NOT commit
### Code Review
1. Flight Director spawns **Reviewer** to evaluate all uncommitted changes
2. If **Accessibility Reviewer** is enabled and leg involves UI changes,
spawn in parallel with Reviewer
3. If issues: Flight Director spawns new **Developer** to fix
4. Loop until all reviewers signal [HANDOFF:confirmed] — max 3 cycles
### Commit
1. Flight Director spawns **Developer** to commit
2. Developer commits code + artifacts, signals [COMPLETE:leg]
## Template Variables
The Flight Director substitutes these variables in prompts at runtime:
| Variable | Description | Available In |
|----------|-------------|-------------|
| `{project-slug}` | Project identifier from projects.md | All prompts |
| `{flight-number}` | Current flight number | All prompts |
| `{leg-number}` | Current leg number | Leg-scoped prompts |
| `{leg-artifact-path}` | Path to the leg artifact file | review-leg-design |
| `{working-directory}` | Resolved working directory for the agent (project root for branch strategy, worktree path for worktree strategy) | All prompts |
| `{reviewer-issues}` | Full text of reviewer feedback (dynamic) | fix-review-issues |
## Prompts
### Developer: Review Leg Design
```
role: developer
phase: leg-design-review
project: {project-slug}
flight: {flight-number}
leg: {leg-number}
action: review-leg-design
Read the leg artifact at {leg-artifact-path}. Cross-reference its acceptance
criteria, implementation guidance, and file references against the actual codebase.
Evaluate:
1. Acceptance criteria — specific, verifiable, complete?
2. Implementation guidance — complete and correctly ordered?
3. Edge cases — missing scenarios?
4. Codebase state — account for working tree, existing tooling, uncommitted changes?
5. File/line references — accurate against current codebase?
6. Dependencies — prerequisite legs completed? Outputs available?
Provide structured output:
**Overall assessment**: approve | approve with changes | needs rework
**Issues** (ranked by severity):
- [high/medium/low] Description — recommended fix
**Suggestions** (non-blocking):
- Description
**Questions** (for the designer):
- Question
```
### Developer: Implement
```
role: developer
phase: leg-implementation
project: {project-slug}
flight: {flight-number}
leg: {leg-number}
action: implement
Read leg artifact. Update leg status to in-flight. Implement to acceptance criteria.
Run tests with a timeout flag appropriate to this project's test runner — fail fast,
do not wait indefinitely for hanging tests. If a test hangs, isolate and fix it.
Update flight log with outcomes. Propagate changes to artifacts (flight, mission, leg),
CLAUDE.md, README, and other project documentation as needed. Do NOT commit yet —
signal [HANDOFF:review-needed] when implementation is complete.
```
### Reviewer: Review
```
role: reviewer
phase: leg-review
project: {project-slug}
flight: {flight-number}
leg: {leg-number}
action: review
Review all changes since the last commit. Evaluate against:
1. Leg acceptance criteria — are all criteria met?
2. Code quality — style, clarity, maintainability
3. Correctness — edge cases, error handling, security
4. Tests — coverage, meaningful assertions, no regressions
5. Artifacts — flight log updated, leg status correct
Signal [HANDOFF:confirmed] if all changes are satisfactory.
If issues found, list them with severity (blocking/non-blocking) and specific
file:line references.
```
### Accessibility Reviewer: Review Accessibility
```
role: accessibility-reviewer
phase: leg-review
project: {project-slug}
flight: {flight-number}
leg: {leg-number}
action: review-accessibility
Review all UI changes since the last commit for accessibility compliance.
Evaluate against:
1. WCAG 2.1 AA — do changes meet Level AA success criteria?
2. Semantic HTML — proper heading hierarchy, landmark regions, form labels?
3. Keyboard navigation — all interactive elements reachable and operable?
4. Screen readers — ARIA attributes correct and meaningful? Live regions?
5. Color and contrast — minimum 4.5:1 for text, 3:1 for large text/UI?
6. Focus management — visible focus indicators, logical tab order?
Signal [HANDOFF:confirmed] if all changes are accessible.
If issues found, list them with severity (blocking/non-blocking), WCAG criterion
reference, and specific file:line references.
```
### Developer: Fix Review Issues
```
role: developer
phase: leg-implementation
project: {project-slug}
flight: {flight-number}
leg: {leg-number}
action: fix-review-issues
Address the following review feedback:
{reviewer-issues}
Fix all blocking issues. Non-blocking issues: fix if straightforward, otherwise
note as accepted. Signal [HANDOFF:review-needed] when fixes are complete.
```
### Developer: Commit
```
role: developer
phase: leg-implementation
project: {project-slug}
flight: {flight-number}
leg: {leg-number}
action: commit
Review has passed. Before committing, complete ALL post-completion checklist items
in the leg artifact:
1. Check off all acceptance criteria in the leg artifact
2. Update leg status to completed
3. Check off this leg in flight.md
4. If final leg: update flight.md status to landed, check off flight in mission.md
Then commit all changes (code + artifacts) with appropriate message.
Signal [COMPLETE:leg].
```

74
container/mission-control/.claude/skills/init-project/defaults/agent-crews/mission-debrief.md Normal file
View File

@@ -0,0 +1,74 @@
# Mission Debrief — Project Crew
Crew definitions for post-mission retrospective. The Flight Director interviews
both the human and a project-side Architect to capture strategic technical perspective.
## Crew
### Architect
- **Context**: {project}/
- **Model**: Sonnet
- **Role**: Provides architectural perspective on mission outcomes. Evaluates
whether the system evolved well across flights, identifies structural issues,
and assesses long-term maintainability of what was built.
- **Actions**: debrief-interview
## Interaction Protocol
### Architect Interview
1. Flight Director loads full mission context (all flights, logs, debriefs, code)
2. Flight Director spawns **Architect** to review overall system evolution
3. Architect examines architectural changes across all flights
4. Architect provides structured debrief input
### Human Interview
1. Flight Director interviews human with mission-level questions
2. Covers coordination experience, outcome satisfaction, process feedback
### Synthesis
1. Flight Director synthesizes Architect input + human input + document analysis
2. Generates mission debrief artifact
## Template Variables
The Flight Director substitutes these variables in prompts at runtime:
| Variable | Description |
|----------|-------------|
| `{project-slug}` | Project identifier from projects.md |
## Prompts
### Architect: Debrief Interview
```
role: architect
phase: mission-debrief
project: {project-slug}
action: debrief-interview
Review the system changes produced across all flights in this mission. Examine
the architectural evolution, pattern consistency, and structural health.
Provide structured input for the debrief:
**Architectural Assessment**:
- Did the system's architecture improve, maintain, or degrade?
- Are there structural issues that emerged across flights?
- Were design decisions consistent across the mission?
**Pattern Analysis**:
- What patterns were established? Are they good ones?
- Is there inconsistency that should be reconciled?
- Are there reusable patterns worth documenting?
**Technical Debt**:
- What debt was introduced across the mission?
- What's the priority for addressing it?
- Are there quick wins vs. long-term concerns?
**Forward-Looking**:
- What architectural considerations should the next mission account for?
- Are there scaling or performance concerns on the horizon?
- What documentation or conventions should be established?
```

72
container/mission-control/.claude/skills/init-project/defaults/agent-crews/mission-design.md Normal file
View File

@@ -0,0 +1,72 @@
# Mission Design — Project Crew
Crew definitions for mission planning. The Flight Director interviews the human
and uses project-side agents to validate technical viability.
## Crew
### Architect
- **Context**: {project}/
- **Model**: Sonnet
- **Role**: Validates technical viability of proposed outcomes. Ensures business
goals align with what's actually possible given the codebase, stack, and
constraints. Does NOT add implementation details — focuses on feasibility,
risks, and architectural implications.
- **Actions**: validate-mission
## Interaction Protocol
### Research & Interview
1. Flight Director researches codebase and external context
2. Flight Director interviews human about outcomes, stakeholders, constraints, criteria
3. Human must explicitly sign off before proceeding — iterate until approved
### Technical Viability Check
1. Flight Director spawns **Architect** to review draft mission against codebase
2. Architect evaluates: Are proposed outcomes achievable? Are there technical risks
the mission doesn't account for? Does the stack support what's being asked?
3. Architect provides assessment — feasible / feasible with caveats / not feasible
4. Flight Director incorporates feedback, re-interviews human if scope changes
5. Human gives final sign-off
## Template Variables
The Flight Director substitutes these variables in prompts at runtime:
| Variable | Description |
|----------|-------------|
| `{project-slug}` | Project identifier from projects.md |
## Prompts
### Architect: Validate Mission
```
role: architect
phase: mission-design
project: {project-slug}
action: validate-mission
Read the draft mission artifact. Cross-reference proposed outcomes and success
criteria against the actual codebase, stack, and project constraints.
Evaluate:
1. Technical feasibility — can the proposed outcomes be achieved with this stack?
2. Architectural implications — does this require significant structural changes?
3. Risk factors — what technical risks could block success?
4. Constraints accuracy — are stated constraints complete and correct?
5. Sizing — is the scope realistic for a mission (days-to-weeks)?
Provide structured output:
**Feasibility**: feasible | feasible with caveats | not feasible
**Risks** (ranked by impact):
- [high/medium/low] Description — mitigation
**Caveats** (if feasible with caveats):
- Description
**Questions** (for the Flight Director):
- Question
```

592
container/mission-control/.claude/skills/init-project/defaults/agent-crews/routine-maintenance.md Normal file
View File

@@ -0,0 +1,592 @@
# Routine Maintenance — Project Crew
Crew definitions for codebase health inspection. The Flight Director
coordinates specialist reviewers for automated checks and an Architect
for severity assessment and roundtable moderation.
## Crew
### Inspector
- **Context**: {project}/
- **Model**: Sonnet
- **Role**: Performs broad read-only codebase inspection across all applicable
categories. Runs test suites, linters, type checkers, audit commands, and
manual code review. Returns structured findings without modifying any files.
- **Actions**: inspect-codebase
### Security Reviewer
- **Context**: {project}/
- **Model**: Sonnet
- **Role**: Performs focused manual security review of authentication flows,
injection surfaces, secrets handling, CORS/CSP configuration, and data
exposure risks. Goes deeper than the Inspector's Category 1 automated checks
with targeted code path analysis.
- **Actions**: review-security
### CI/CD Reviewer (optional)
- **Context**: {project}/
- **Model**: Sonnet
- **Enabled**: false (enable when project has CI/CD pipelines)
- **Role**: Reviews CI/CD pipeline configuration, build security, deployment
practices, and environment consistency. Evaluates pipeline definitions,
secret management in CI, and deployment safeguards.
- **Actions**: review-cicd
### Accessibility Reviewer (optional)
- **Context**: {project}/
- **Model**: Sonnet
- **Enabled**: false (enable when project has user-facing UI)
- **Role**: Reviews codebase for accessibility compliance against WCAG 2.1 AA
standards. Evaluates semantic HTML, keyboard navigation, screen reader
compatibility, color contrast, ARIA usage, and focus management.
- **Actions**: review-accessibility
### Architect
- **Context**: {project}/
- **Model**: Opus
- **Role**: Reviews all reviewer findings alongside debrief context. Assigns
severity per finding, challenges questionable assessments, moderates
roundtable discussion with specialist reviewers, and produces final codebase
assessment with maintenance scope recommendation.
- **Actions**: assess-findings, moderate-roundtable
## Separation Rules
- All reviewers are strictly **read-only** — they may run commands but must NEVER modify files
- Each reviewer operates independently during Phase 4 — no cross-reviewer communication
- The Architect sees all reviewer findings but not their internal reasoning
- Roundtable discussion is mediated by the Flight Director, not direct agent-to-agent
**Note:** Handoff signals are not used in this crew. The routine-maintenance workflow is
sequential (review → assess → roundtable → report) and does not use the leg-based
handoff protocol.
## Interaction Protocol
### Delegation Planning
1. Flight Director loads context, conducts scoping interview with human
2. Flight Director assesses project size and identifies module boundaries
3. Flight Director builds delegation plan (agent count, scope assignments, partitioning)
4. Human approves or adjusts the plan
### Specialist Review
1. Flight Director spawns agents per the delegation plan — Inspector(s) + Security Reviewer always, CI/CD and Accessibility if enabled
2. Each agent receives its scope assignment and output discipline rules
3. All reviewers perform read-only checks and return structured findings
4. For partitioned Inspectors: Flight Director merges and de-duplicates findings
### Initial Assessment
1. Flight Director spawns **Architect** (Opus) with all reviewer findings + debrief context
2. Architect assigns initial severity per finding
3. Architect raises challenges or questions directed at specific reviewers
### Roundtable
1. Flight Director routes Architect's challenges to the relevant reviewers
2. Each challenged reviewer responds with evidence, rebuttals, or concurrence
3. Flight Director collects responses and spawns Architect for final resolution
4. Architect produces final assessment incorporating roundtable discussion
5. Max 2 roundtable cycles — unresolved disagreements go to the human
### Human Review and Scoping
1. Flight Director presents findings to human, grouped by severity
2. Human confirms, overrides, or adjusts findings
3. If Maintenance Required: Flight Director recommends a shortlist (~5-7 items); human selects scope for maintenance mission
4. Deferred findings remain in the report for future cycles
### Synthesis
1. Flight Director generates maintenance report artifact
2. If confirmed: Flight Director creates maintenance mission scaffold
## Template Variables
The Flight Director substitutes these variables in prompts at runtime:
| Variable | Description |
|----------|-------------|
| `{project-slug}` | Project identifier from projects.md |
| `{applicable-categories}` | Numbered list of categories to inspect (1-7 always, 8-10 conditional) |
| `{project-stack}` | Language, framework, test runner, linter, formatter, type checker, audit tool |
| `{known-debt}` | Debt items from mission debrief and flight debriefs (if available, otherwise "None — ad-hoc inspection") |
| `{known-security-debt}` | Security-specific debt items extracted from debriefs (if available, otherwise "None") |
| `{known-cicd-debt}` | CI/CD-specific debt items extracted from debriefs (if available, otherwise "None") |
| `{areas-of-concern}` | User-specified areas of concern from scoping interview |
| `{scope-assignment}` | Scope restriction from the delegation plan (files, directories, or "full project") |
| `{all-reviewer-findings}` | Combined structured findings from all reviewers (used in Architect prompts) |
| `{architect-challenges}` | Architect's challenges directed at a specific reviewer (used in roundtable) |
| `{roundtable-responses}` | All reviewer rebuttals and responses from the roundtable (used in resolution) |
## Prompts
### Inspector: Inspect Codebase
```
role: inspector
phase: routine-maintenance
project: {project-slug}
action: inspect-codebase
Perform a read-only codebase inspection across the following categories:
{applicable-categories}
Project stack: {project-stack}
Known debt from prior debriefs, if available (do not re-flag as new discoveries):
{known-debt}
User areas of concern:
{areas-of-concern}
IMPORTANT: You are strictly READ-ONLY. You may run test suites, linters, type
checkers, audit commands, and read any file. You must NEVER modify source files,
configuration, dependencies, or any other project file.
**Scope assignment**: If a scope restriction is provided, inspect only the
specified files and directories. Run automated tools against the full project
(tools are fast and comprehensive), but limit manual code review to the assigned
scope. If no scope restriction is given, inspect the full project.
For each applicable category, perform the checks listed below and report findings.
**Category 1 — Security**:
- Review auth paths (focus on recently changed code if mission context is available)
- Check input sanitization on endpoints
- Verify CORS/CSP configuration
- Scan for hardcoded secrets (API keys, tokens, passwords)
- Review third-party data flow for exposure risks
**Category 2 — Test Systems**:
- Run the test suite and report results
- Check coverage delta (if tooling available)
- Find new code paths without test coverage
- Detect flaky tests (tests that pass/fail inconsistently)
- Check test performance (slow tests)
- Find hardcoded test data that should be fixtures
**Category 3 — Dependency Health**:
- Run the dependency audit command (npm audit, cargo audit, etc.)
- Check for outdated dependencies
- Find unused dependencies
- Verify lockfile is consistent
- Check license compliance
- Check for Dependabot/Renovate PRs and security alerts
- Assess auto-merge eligibility for patch updates
**Category 4 — Code Quality**:
- Run linter and formatter check (report violations, do NOT fix)
- Find dead code (unused exports, unreachable branches)
- Grep for TODOs/FIXMEs/HACKs (focus on recently introduced ones if mission context is available)
- Detect code duplication
- Check pattern consistency with existing codebase
**Category 5 — Type & API Safety**:
- Run the type checker and report errors
- Find `any` casts (TypeScript), `unsafe` blocks (Rust), or equivalent
- Check for unhandled errors or missing error types
- Detect API contract drift (mismatched types between client/server)
- Find deprecated API usage
**Category 6 — Documentation**:
- Check README accuracy against current state
- Verify new public interfaces have documentation
- Find stale comments referencing old behavior
- Check CHANGELOG for completeness
- Verify CLAUDE.md accuracy
**Category 7 — Git & Branch Hygiene**:
- List stale branches (merged but not deleted)
- Find large committed files (>1MB)
- Scan for secrets in recent git history
- Check commit message quality
- Check for GitHub/remote warnings (secret scanning, code scanning alerts)
- Find merge conflicts against main
- Check upstream divergence
**Category 8 — CI/CD Pipeline** (if applicable):
- Check CI status on main/default branch
- Detect build time regression
- Find skipped or disabled checks
- Check config drift between environments
**Category 9 — Infrastructure & Config** (if applicable):
- Check env var documentation (.env.example vs actual usage)
- Find pending database migrations
- Find temporary feature flags that should be removed
**Category 10 — Performance & Observability** (if applicable):
- Find new operations without logging/tracing
- Detect potential N+1 queries
- Check bundle size (if web project)
- Find resource cleanup issues (unclosed connections, missing cleanup)
**Output discipline**: Keep findings concise. Do not paste full command output,
full file contents, or long dependency lists. Summarize and reference.
**Output format**: Return findings as a structured list per category:
## Category {N}: {Name}
### Finding: {title}
- **Evidence**: {one-line summary with file paths and line numbers}
- **Impact**: {what could go wrong}
- **Recommendation**: {what to do about it}
Include code excerpts only for Critical or High severity findings.
If a category has no issues, report:
## Category {N}: {Name}
No issues found.
```
### Security Reviewer: Review Security
```
role: security-reviewer
phase: routine-maintenance
project: {project-slug}
action: review-security
Perform a focused, manual security review of the codebase. You go deeper than
automated scanning — trace actual code paths and evaluate security posture.
Project stack: {project-stack}
Known security debt from prior debriefs (do not re-flag as new discoveries):
{known-security-debt}
User areas of concern:
{areas-of-concern}
IMPORTANT: You are strictly READ-ONLY. You may run commands and read any file.
You must NEVER modify source files, configuration, dependencies, or any other
project file.
**Scope assignment**: Review only the files and areas specified. If no scope
restriction is given, review the full project.
**Output discipline**: Keep findings concise. Include code excerpts only for
Critical or High severity findings. Do not paste full file contents or raw
command output.
**Review areas**:
1. **Authentication & Authorization**
- Trace auth flows end-to-end (login, token refresh, logout)
- Check for missing auth checks on protected routes/endpoints
- Verify role-based access control is enforced consistently
- Look for privilege escalation paths
2. **Injection Surfaces**
- SQL/NoSQL injection: check all database queries for parameterization
- Command injection: check shell executions, subprocess calls
- XSS: check output encoding in templates and API responses
- Path traversal: check file system operations with user input
3. **Secrets & Configuration**
- Scan for hardcoded credentials, API keys, tokens in source
- Check .env files are gitignored
- Verify secrets are not logged or included in error responses
- Check for overly permissive CORS configuration
4. **Data Handling**
- Review PII/sensitive data flows — where is it stored, logged, transmitted?
- Check encryption at rest and in transit
- Verify sensitive data is not cached inappropriately
- Check for data leakage in error messages or debug output
5. **Dependency Risk**
- Cross-reference critical dependencies against known CVE databases
- Check for dependencies with known supply-chain risks
- Verify integrity checks (lockfile hashes, checksums)
**Output format**: Return findings as a structured list:
### Finding: {title}
- **Severity estimate**: critical | high | medium | low
- **Attack vector**: {how this could be exploited}
- **Evidence**: {specific code paths, file:line references}
- **Recommendation**: {what to do about it}
If no security issues found, state: "No security issues identified."
```
### CI/CD Reviewer: Review CI/CD
```
role: cicd-reviewer
phase: routine-maintenance
project: {project-slug}
action: review-cicd
Perform a focused review of the project's CI/CD pipeline configuration,
build security, and deployment practices.
Project stack: {project-stack}
Known CI/CD debt from prior debriefs (do not re-flag as new discoveries):
{known-cicd-debt}
User areas of concern:
{areas-of-concern}
IMPORTANT: You are strictly READ-ONLY. You may run commands and read any file.
You must NEVER modify source files, configuration, dependencies, or any other
project file.
**Output discipline**: Keep findings concise. Include code excerpts only for
Critical or High severity findings. Do not paste full file contents or raw
command output.
**Review areas**:
1. **Pipeline Configuration**
- Review pipeline definitions (GitHub Actions, GitLab CI, Concourse, etc.)
- Check for outdated action/image versions
- Verify branch protection rules are consistent with pipeline triggers
- Detect redundant or overlapping pipeline steps
2. **Build Security**
- Check for secrets exposed in build logs or artifacts
- Verify pipeline secrets are scoped appropriately (not org-wide when repo-level suffices)
- Check for unpinned dependencies in build steps (e.g., `uses: action@main` vs `@v4.1.0`)
- Review build artifact permissions and retention policies
3. **Deployment Safeguards**
- Verify deployment gates exist (approval steps, environment protection rules)
- Check rollback capability — is there a documented or automated rollback path?
- Verify environment promotion flow (dev → staging → prod) is enforced
- Check for drift between environment configurations
4. **Pipeline Health**
- Check recent build success rates and durations
- Identify flaky pipeline steps
- Find disabled or skipped checks that should be active
- Check for resource waste (oversized runners, unnecessary matrix builds)
**Output format**: Return findings as a structured list:
### Finding: {title}
- **Severity estimate**: critical | high | medium | low
- **Evidence**: {specific config files, pipeline definitions, line references}
- **Impact**: {what could go wrong}
- **Recommendation**: {what to do about it}
If no CI/CD issues found, state: "No CI/CD issues identified."
```
### Accessibility Reviewer: Review Accessibility
```
role: accessibility-reviewer
phase: routine-maintenance
project: {project-slug}
action: review-accessibility
Perform a focused accessibility review of the project's user-facing UI.
Evaluate against WCAG 2.1 AA standards.
Project stack: {project-stack}
IMPORTANT: You are strictly READ-ONLY. You may run commands and read any file.
You must NEVER modify source files, configuration, dependencies, or any other
project file.
**Output discipline**: Keep findings concise. Include code excerpts only for
Critical or High severity findings. Do not paste full file contents or raw
command output.
**Review areas**:
1. **Semantic HTML & Structure**
- Check heading hierarchy (h1-h6 in logical order)
- Verify landmark regions (main, nav, aside, footer)
- Check form labels and fieldset/legend usage
- Verify list markup for list-like content
2. **Keyboard Navigation**
- Check all interactive elements are reachable via Tab
- Verify custom widgets have appropriate keyboard handlers
- Check for keyboard traps (modals, dropdowns)
- Verify skip-to-content links exist
3. **Screen Reader Compatibility**
- Check ARIA attributes for correctness and necessity
- Verify dynamic content updates use live regions
- Check image alt text (present, meaningful, not redundant)
- Verify form error messages are associated with inputs
4. **Visual & Color**
- Check text contrast ratios (4.5:1 normal, 3:1 large text)
- Verify UI component contrast (3:1 against background)
- Check that color is not the sole indicator of meaning
- Verify visible focus indicators on all interactive elements
5. **Motion & Timing**
- Check for prefers-reduced-motion support on animations
- Verify no auto-playing media without controls
- Check for appropriate timeouts with user notification
**Output format**: Return findings as a structured list:
### Finding: {title}
- **WCAG criterion**: {e.g., 1.1.1 Non-text Content, Level A}
- **Severity estimate**: critical | high | medium | low
- **Evidence**: {specific components, file:line references}
- **Recommendation**: {what to do about it}
If no accessibility issues found, state: "No accessibility issues identified."
```
### Architect: Assess Findings
```
role: architect
phase: routine-maintenance
project: {project-slug}
action: assess-findings
Review all specialist findings and assign severity ratings. You have access to:
- All reviewer findings (provided below)
- Known debt context from debriefs and prior maintenance reports (if available)
{all-reviewer-findings}
Known debt from debriefs, if available (already acknowledged — note as "previously identified" if re-found):
{known-debt}
For each finding, assign one of:
- **Pass** — No issue (reviewer flagged something that is actually fine)
- **Advisory** — Minor issue, acceptable to defer
- **Action Required** — Should be addressed before next major work cycle
- **Critical** — Blocks further work, immediate attention needed
**Assessment criteria**:
- Does this finding represent a real risk, or is it noise?
- Is the severity proportional to the actual impact?
- Would this compound if left for another cycle?
- Is this a new discovery or previously acknowledged debt?
- Do multiple reviewers corroborate the same issue?
- Are any reviewer assessments questionable — too alarmist or too dismissive?
**Challenge reviewers** where you disagree or need clarification. For each
challenge, name the reviewer and provide your specific question or objection.
This initiates the roundtable discussion.
**Output format**:
## Overall Assessment
{Flight Ready | Maintenance Required}
## Findings
| # | Source | Category | Finding | Initial Severity | New/Known | Notes |
|---|--------|----------|---------|-----------------|-----------|-------|
| 1 | {reviewer} | {cat} | {title} | {severity} | {new/known} | {brief note} |
## Challenges for Roundtable
### To {Reviewer Name}: {question or objection}
{Context for why you're challenging this finding — what seems off, what
additional evidence would change your assessment, or why you think the
severity should be different.}
## Severity Summary
- Critical: {N}
- Action Required: {N}
- Advisory: {N}
- Pass: {N}
## Recommended Maintenance Scope
(Only if Maintenance Required)
Group related Action Required and Critical findings into suggested flight scopes:
### Flight: {suggested title}
- Finding #{N}: {title}
- Finding #{N}: {title}
- Rationale: {why these group together}
```
### Reviewer: Roundtable Rebuttal
```
role: {reviewer-role}
phase: routine-maintenance
project: {project-slug}
action: roundtable-rebuttal
The Architect has challenged one or more of your findings during the
severity assessment roundtable. Respond to each challenge with evidence.
Architect's challenges:
{architect-challenges}
For each challenge:
1. **Provide additional evidence** — code paths, specific examples, tool output
that supports your finding
2. **Concede if appropriate** — if the Architect raises a valid point, adjust
your assessment rather than defending a weak position
3. **Clarify misunderstandings** — if the Architect misread your finding,
restate it with more precision
Be direct and evidence-based. The goal is consensus, not debate for its own sake.
**Output format**:
### Re: {Architect's challenge title}
- **Response**: {concur | rebut | clarify}
- **Evidence**: {additional code paths, line references, tool output}
- **Revised assessment** (if changed): {updated severity or recommendation}
```
### Architect: Roundtable Resolution
```
role: architect
phase: routine-maintenance
project: {project-slug}
action: roundtable-resolution
Review the roundtable responses from specialist reviewers and produce your
final assessment.
Reviewer responses:
{roundtable-responses}
For each challenged finding:
1. **Weigh the evidence** — did the reviewer provide convincing support?
2. **Assign final severity** — this is your call, but account for reviewer expertise
3. **Note reasoning** — briefly explain why you maintained or changed severity
If any disagreements remain unresolved, flag them for human review rather than
forcing consensus.
**Output format**:
## Roundtable Resolution
### Finding #{N}: {title}
- **Original severity**: {severity}
- **Reviewer response**: {concur | rebut | clarify} — {summary}
- **Final severity**: {severity}
- **Reasoning**: {why}
## Updated Overall Assessment
{Flight Ready | Maintenance Required}
## Updated Severity Summary
- Critical: {N}
- Action Required: {N}
- Advisory: {N}
- Pass: {N}
## Unresolved Disagreements (if any)
{Finding and both perspectives — for human to decide}
## Updated Recommended Maintenance Scope
(Only if Maintenance Required — incorporate roundtable outcomes)
### Flight: {suggested title}
- Finding #{N}: {title}
- Finding #{N}: {title}
- Rationale: {why these group together}
```

104
container/mission-control/.claude/skills/init-project/migrations.md Normal file
View File

@@ -0,0 +1,104 @@
# Init-Project Migrations
When `/init-project` runs, it checks for legacy directory layouts from earlier versions of Flight Control and offers to migrate them. Migrations are idempotent — they only apply when the old layout is detected and the new layout doesn't yet exist.
## Migration Registry
### 001 — Rename `.flight-ops/` to `.flightops/`
Early versions of Flight Control used `.flight-ops/` (with a hyphen). The current convention is `.flightops/` (no hyphen).
**Detection** (returns true if migration is needed):
```bash
[[ -d "{target-project}/.flight-ops" && ! -d "{target-project}/.flightops" ]]
```
**Actions:**
1. Rename the directory:
```bash
mv "{target-project}/.flight-ops" "{target-project}/.flightops"
```
2. Update `.gitignore` if it references the old name:
```bash
sed -i 's/\.flight-ops/\.flightops/g' "{target-project}/.gitignore"
```
**User message:**
> Renaming `.flight-ops/` → `.flightops/` (updated naming convention)
---
### 002 — Rename `phases/` to `agent-crews/`
Early versions stored crew definitions in `.flightops/phases/`. The current convention is `.flightops/agent-crews/`.
**Detection** (returns true if migration is needed):
```bash
[[ -d "{target-project}/.flightops/phases" && ! -d "{target-project}/.flightops/agent-crews" ]]
```
> **Note:** This runs after migration 001, so it checks the post-rename `.flightops/` path.
**Actions:**
1. Rename the subdirectory:
```bash
mv "{target-project}/.flightops/phases" "{target-project}/.flightops/agent-crews"
```
**User message:**
> Renaming `phases/` → `agent-crews/` (updated naming convention)
---
### 003 — Update lifecycle states to unified model
Flight Control now uses a unified lifecycle for both flights and legs: `planning → ready → in-flight → landed → completed` (or `aborted`). This replaces the old divergent states:
- **Flights**: `diverted` → `aborted`; added `completed` after `landed`
- **Legs**: `queued` → `planning`; `review` → `landed`; `blocked` → `aborted`; added `ready` and `completed`
**Detection** (returns true if migration is needed):
```bash
grep -rql 'queued\|diverted\|blocked\|review.*completed' "{target-project}/.flightops/ARTIFACTS.md" 2>/dev/null
```
> **Note:** This runs after migrations 001 and 002, so it checks the post-rename `.flightops/` path.
**Actions:**
1. Update state definitions in ARTIFACTS.md:
- Replace flight status line: `planning | ready | in-flight | landed | diverted` → `planning | ready | in-flight | landed | completed | aborted`
- Replace leg status line: `queued | in-flight | review | completed | blocked` → `planning | ready | in-flight | landed | completed | aborted`
- Replace flight state tracking: `planning` → `ready` → `in-flight` → `landed` (or `diverted`) → `planning` → `ready` → `in-flight` → `landed` → `completed` (or `aborted`)
- Replace leg state tracking: `queued` → `in-flight` → `review` → `completed` (or `blocked`) → `planning` → `ready` → `in-flight` → `landed` → `completed` (or `aborted`)
- Replace `landed | diverted` → `landed | aborted` in debrief templates
- Replace `landed/diverted` → `landed/aborted` in debrief templates
- Replace `completed | in-flight | blocked` → `completed | landed | in-flight | aborted` in flight log templates
2. Update existing artifact files in the project (if any):
- In flight artifacts: replace `**Status**: diverted` → `**Status**: aborted`
- In leg artifacts: replace `**Status**: queued` → `**Status**: planning`, `**Status**: review` → `**Status**: landed`, `**Status**: blocked` → `**Status**: aborted`
- In flight log entries: replace `**Status**: blocked` → `**Status**: aborted`
Find artifacts using the locations defined in ARTIFACTS.md (typically `missions/` directory for file-based projects).
**User message:**
> Updating lifecycle states to unified model: flights and legs now share `planning → ready → in-flight → landed → completed (or aborted)`
---
## Adding Future Migrations
To add a new migration:
1. Assign the next sequential ID (e.g., `003`)
2. Write a **Detection** check that returns true only when the migration is needed and false if already applied (idempotent)
3. List the **Actions** to perform — prefer `mv` over copy-and-delete to preserve file contents and git history
4. Write a short **User message** shown during the migration summary
5. Consider ordering — if the migration depends on a previous one having run, note that in the detection section
6. Keep migrations non-destructive: rename and update references, never delete user content

575
container/mission-control/.claude/skills/init-project/templates/ARTIFACTS-files.md Normal file
View File

@@ -0,0 +1,575 @@
# Artifact System: Filesystem
This project stores Flight Control artifacts as markdown files in the repository.
## Directory Structure
```
{project}/
├── missions/
│ └── {NN}-{mission-slug}/
│ ├── mission.md
│ ├── mission-debrief.md
│ └── flights/
│ └── {NN}-{flight-slug}/
│ ├── flight.md
│ ├── flight-log.md
│ ├── flight-briefing.md
│ ├── flight-debrief.md
│ └── legs/
│ └── {NN}-{leg-slug}.md
└── maintenance/
└── {YYYY-MM-DD}.md
```
## Naming Conventions
- **Slugs**: Lowercase, kebab-case, derived from title (e.g., "User Authentication" → `user-authentication`)
- **Sequence numbers**: Missions, flights, and legs use two-digit prefixes (`01`, `02`, etc.) for ordering
---
## Core Artifacts
### Mission
| Property | Value |
|----------|-------|
| Location | `missions/{NN}-{slug}/mission.md` |
| Created | During mission planning |
| Updated | Until status changes to `active` |
**Format:**
```markdown
# Mission: {Title}
**Status**: planning | active | completed | aborted
## Outcome
What success looks like in human terms.
## Context
Why this mission matters now. Background information.
## Success Criteria
- [ ] Criterion 1 (observable, binary)
- [ ] Criterion 2
- [ ] Criterion 3
## Stakeholders
Who cares about this outcome and why.
## Constraints
Non-negotiable boundaries.
## Environment Requirements
- Development environment (devcontainer, local toolchain, cloud IDE)
- Runtime requirements (GUI, audio hardware, network access)
- Special tooling (Docker, specific CLI versions)
## Open Questions
Unknowns that need resolution during execution.
## Known Issues
Emergent blockers and issues discovered during execution. Add items here as flights surface problems that affect the broader mission — things not anticipated during planning but visible at the mission level.
- [ ] {Issue description} — discovered in Flight {N}, affects {scope}
## Flights
> **Note:** These are tentative suggestions, not commitments. Flights are planned and created one at a time as work progresses. This list will evolve based on discoveries during implementation.
- [ ] Flight 1: {description}
- [ ] Flight 2: {description}
- [ ] Flight N *(optional)*: Alignment — vibe coding session for creative collaboration and hands-on adjustments
```
---
### Flight
| Property | Value |
|----------|-------|
| Location | `missions/{mission}/flights/{NN}-{slug}/flight.md` |
| Created | During flight planning |
| Updated | Until status changes to `in-flight` |
**Format:**
```markdown
# Flight: {Title}
**Status**: planning | ready | in-flight | landed | completed | aborted
**Mission**: [{Mission Title}](../../mission.md)
## Contributing to Criteria
- [ ] {Relevant success criterion 1}
- [ ] {Relevant success criterion 2}
---
## Pre-Flight
### Objective
What this flight accomplishes (one paragraph).
### Open Questions
- [ ] Question needing resolution
- [x] Resolved question → see Design Decisions
### Design Decisions
**{Decision Title}**: {Choice made}
- Rationale: Why this choice
- Trade-off: What we're giving up
### Prerequisites
- [ ] {What must be true before execution}
### Pre-Flight Checklist
- [ ] All open questions resolved
- [ ] Design decisions documented
- [ ] Prerequisites verified
- [ ] Validation approach defined
- [ ] Legs defined
---
## In-Flight
### Technical Approach
How the objective will be achieved.
### Checkpoints
- [ ] {Milestone 1}
- [ ] {Milestone 2}
### Adaptation Criteria
**Divert if**:
- {Condition requiring re-planning}
**Acceptable variations**:
- {Minor changes that don't require diversion}
### Legs
> **Note:** These are tentative suggestions, not commitments. Legs are planned and created one at a time as the flight progresses. This list will evolve based on discoveries during implementation.
- [ ] `{leg-slug}` - {Brief description}
- [ ] `{leg-slug}` - {Brief description}
- [ ] `uat-and-alignment` *(optional)* - Guided UAT session with iterative fixes
---
## Post-Flight
### Completion Checklist
- [ ] All legs completed
- [ ] Code merged
- [ ] Tests passing
- [ ] Documentation updated
### Verification
How to confirm the flight achieved its objective.
```
---
### Leg
| Property | Value |
|----------|-------|
| Location | `missions/{mission}/flights/{flight}/legs/{NN}-{slug}.md` |
| Created | Before leg execution |
| Updated | Never once `in-flight` (immutable) |
**Format:**
```markdown
# Leg: {slug}
**Status**: planning | ready | in-flight | landed | completed | aborted
**Flight**: [{Flight Title}](../flight.md)
## Objective
Single sentence: what this leg accomplishes.
## Context
- Relevant design decisions from the flight
- How this fits into the broader technical approach
- Key learnings from prior legs (from flight log)
## Inputs
What exists before this leg runs:
- Files that must exist
- State that must be true
## Outputs
What exists after this leg completes:
- Files created or modified
- State changes
## Acceptance Criteria
- [ ] Criterion 1 (specific, observable)
- [ ] Criterion 2
- [ ] Criterion 3
## Verification Steps
How to confirm each criterion is met:
- {Command or manual check for criterion 1}
- {Command or manual check for criterion 2}
## Implementation Guidance
1. **{First step}**
- Details about what to do
2. **{Second step}**
- Details
## Edge Cases
- **{Edge case 1}**: How to handle
## Files Affected
- `path/to/file.ext` - {What changes}
---
## Post-Completion Checklist
**Complete ALL steps before signaling `[COMPLETE:leg]`:**
- [ ] All acceptance criteria verified
- [ ] Tests passing
- [ ] Update flight-log.md with leg progress entry
- [ ] Set this leg's status to `completed` (in this file's header)
- [ ] Check off this leg in flight.md
- [ ] If final leg of flight:
- [ ] Update flight.md status to `landed`
- [ ] Check off flight in mission.md
- [ ] Commit all changes together (code + artifacts)
```
---
## Supporting Artifacts
### Flight Log
| Property | Value |
|----------|-------|
| Location | `missions/{mission}/flights/{flight}/flight-log.md` |
| Created | When flight is created |
| Updated | Continuously during execution (append-only) |
**Format:**
```markdown
# Flight Log: {Flight Title}
**Flight**: [{Flight Title}](flight.md)
## Summary
Brief overview of execution status and key outcomes.
---
## Leg Progress
### {Leg Name}
**Status**: completed | landed | in-flight | aborted
**Started**: {timestamp}
**Completed**: {timestamp}
#### Changes Made
- {Summary of what was implemented}
#### Notes
{Observations during execution}
---
## Decisions
Runtime decisions not in original plan.
### {Decision Title}
**Context**: Why needed
**Decision**: What was chosen
**Impact**: Effect on flight or future legs
---
## Deviations
Departures from planned approach.
### {Deviation Title}
**Planned**: What the flight specified
**Actual**: What was done instead
**Reason**: Why the deviation was necessary
---
## Anomalies
Unexpected issues encountered.
### {Anomaly Title}
**Observed**: What happened
**Severity**: blocking | degraded | cosmetic
**Resolution**: How handled or "unresolved"
---
## Session Notes
Chronological notes from work sessions.
```
---
### Flight Briefing
| Property | Value |
|----------|-------|
| Location | `missions/{mission}/flights/{flight}/flight-briefing.md` |
| Created | Before flight execution begins |
| Purpose | Pre-flight summary for crew alignment |
**Format:**
```markdown
# Flight Briefing: {Flight Title}
**Date**: {briefing date}
**Flight**: [{Flight Title}](flight.md)
**Status**: Flight is ready for execution
## Mission Context
{Brief reminder of mission outcome and how this flight contributes}
## Objective
{What this flight will accomplish}
## Key Decisions
{Summary of critical design decisions crew should know}
## Risks and Mitigations
| Risk | Mitigation |
|------|------------|
| {risk} | {mitigation} |
## Legs Overview
1. `{leg-slug}` - {description} - {estimated complexity}
2. `{leg-slug}` - {description} - {estimated complexity}
## Environment Requirements
{Any special setup needed before starting}
## Success Criteria
{How we'll know the flight succeeded}
```
---
### Flight Debrief
| Property | Value |
|----------|-------|
| Location | `missions/{mission}/flights/{flight}/flight-debrief.md` |
| Created | After flight lands or diverts |
| Purpose | Post-flight analysis and lessons learned |
**Format:**
```markdown
# Flight Debrief: {Flight Title}
**Date**: {debrief date}
**Flight**: [{Flight Title}](flight.md)
**Status**: {landed | aborted}
**Duration**: {start} - {end}
**Legs Completed**: {X of Y}
## Outcome Assessment
### Objectives Achieved
{What the flight accomplished}
### Mission Criteria Advanced
{Which success criteria this flight contributed to}
## What Went Well
{Specific things that worked effectively}
## What Could Be Improved
### Process
- {Recommendations for flight execution}
### Technical
- {Code quality, architecture, debt}
### Documentation
- {Gaps identified}
## Deviations and Lessons Learned
| Deviation | Reason | Standardize? |
|-----------|--------|--------------|
| {what changed} | {why} | {yes/no} |
## Key Learnings
{Insights for future flights}
## Recommendations
1. {Most impactful recommendation}
2. {Second recommendation}
3. {Third recommendation}
## Action Items
- [ ] {Immediate actions}
- [ ] {Near-term improvements}
```
---
### Mission Debrief
| Property | Value |
|----------|-------|
| Location | `missions/{NN}-{mission}/mission-debrief.md` |
| Created | After mission completes or aborts |
| Purpose | Post-mission retrospective and methodology improvements |
**Format:**
```markdown
# Mission Debrief: {Mission Title}
**Date**: {debrief date}
**Mission**: [{Mission Title}](mission.md)
**Status**: {completed | aborted}
**Duration**: {start} - {end}
**Flights Completed**: {X of Y}
## Outcome Assessment
### Success Criteria Results
| Criterion | Status | Notes |
|-----------|--------|-------|
| {criterion} | {met/not met} | {notes} |
### Overall Outcome
{Did we achieve what we set out to do?}
## Flight Summary
| Flight | Status | Key Outcome |
|--------|--------|-------------|
| {flight} | {landed/aborted} | {outcome} |
## What Went Well
{Effective patterns and successes}
## What Could Be Improved
{Process, planning, execution improvements}
## Lessons Learned
{Insights to carry forward}
## Methodology Feedback
{Improvements to Flight Control process itself}
## Action Items
- [ ] {Follow-up work}
- [ ] {Process improvements}
```
---
### Maintenance Report
| Property | Value |
|----------|-------|
| Location | `maintenance/{YYYY-MM-DD}.md` |
| Created | After a mission or ad-hoc, during routine maintenance |
| Purpose | Codebase health assessment and maintenance recommendation |
**Format:**
```markdown
# Maintenance Report: {YYYY-MM-DD}
**Date**: {report date}
**Triggered by**: [{Mission Title}](missions/{NN}-{slug}/mission.md) *(optional — omit if ad-hoc)*
**Assessment**: {Flight Ready | Maintenance Required}
## Categories Inspected
{Numbered list of categories that were checked}
## Executive Summary
{2-3 sentence overview of codebase health and key findings}
## Findings by Category
### Category {N}: {Name}
| # | Finding | Severity | New/Known | Recommendation |
|---|---------|----------|-----------|----------------|
| {n} | {title} | {severity} | {new/known} | {recommendation} |
**Details:**
{Per-finding evidence with file paths and line numbers}
## Severity Summary
| Severity | Count |
|----------|-------|
| Critical | {N} |
| Action Required | {N} |
| Advisory | {N} |
| Pass | {N} |
## Known Debt Carried Forward
{Debt items from debriefs that were acknowledged but not addressed, or "None — no prior debt context"}
## Recommendations
1. {Most impactful recommendation}
2. {Second recommendation}
3. {Third recommendation}
## Maintenance Mission
{Link to scaffolded mission if created, or "Not required — codebase is flight ready"}
```
---
## State Tracking
States are tracked in the frontmatter or status field of each artifact:
| Artifact | States |
|----------|--------|
| Mission | `planning` → `active` → `completed` (or `aborted`) |
| Flight | `planning` → `ready` → `in-flight` → `landed` → `completed` (or `aborted`) |
| Leg | `planning` → `ready` → `in-flight` → `landed` → `completed` (or `aborted`) |
## Conventions
- **Immutability**: Never modify legs once `in-flight`; create new ones instead
- **Append-only logs**: Flight logs are append-only during execution
- **Flight briefings**: Created before execution, not modified after
- **Debriefs**: Created after completion, may be updated with follow-up notes
- **Mission as briefing**: The mission.md document serves as both definition and briefing (no separate mission-briefing.md)
## Git Workflow
| Property | Value |
|----------|-------|
| Strategy | `branch` |
**Options:**
- **`branch`** (default) — Single-checkout workflow. The orchestrator creates a feature branch and all agents work in the project root. One flight at a time per working copy.
- **`worktree`** — Worktree isolation. The orchestrator creates a git worktree under `.worktrees/` for each flight. Agents work in the worktree path. Parallel flights are possible on a single repo clone.
When using the `worktree` strategy, add `.worktrees/` to `.gitignore`.

408
container/mission-control/.claude/skills/init-project/templates/ARTIFACTS-jira.md Normal file
View File

@@ -0,0 +1,408 @@
# Artifact System: Jira
This project stores Flight Control artifacts as Jira issues.
## Issue Type Mapping
| Flight Control | Jira Issue Type | Hierarchy |
|----------------|-----------------|-----------|
| Mission | Epic | Parent |
| Flight | Story | Child of Epic |
| Leg | Sub-task | Child of Story |
## Setup Questions
Answer these questions when configuring Jira artifacts for your project:
| Question | Answer |
|----------|--------|
| What is the Jira project key? | `PROJECT` |
| JQL query for discovering flight documentation? | (e.g., `project = PROJECT AND labels = flight-control`) |
## Configuration
| Property | Value |
|----------|-------|
| Project Key | `PROJECT` |
| Board | (specify board name or ID) |
| Labels | `flight-control` |
---
## Custom Fields
<!-- Add your project's custom Jira fields here -->
| Custom Field | Jira Field ID | Required | Used For | Notes |
|--------------|---------------|----------|----------|-------|
| (example) Team | `customfield_10001` | Yes | All issues | Select from predefined teams |
| (example) Sprint | `customfield_10002` | No | Stories, Sub-tasks | Assign to sprint |
## Project Rules
<!-- Document project-specific Jira rules and conventions here -->
### Required Fields by Issue Type
**Epic (Mission):**
- (list required fields for your project)
**Story (Flight):**
- (list required fields for your project)
**Sub-task (Leg):**
- (list required fields for your project)
### Workflow Rules
- (document any workflow restrictions or automation rules)
- (e.g., "Stories cannot move to In Progress without Epic Link")
### Naming Conventions
- (document any naming patterns required by your project)
- (e.g., "Epic summaries must start with [MISSION]")
---
## Core Artifacts
### Mission → Epic
| Field | Mapping |
|-------|---------|
| Summary | Mission title |
| Description | See format below |
| Labels | `flight-control`, `mission` |
**Description Format:**
```
## Outcome
{What success looks like in human terms}
## Context
{Why this mission matters now}
## Success Criteria
- [ ] {Criterion 1}
- [ ] {Criterion 2}
## Stakeholders
{Who cares about this outcome}
## Constraints
{Non-negotiable boundaries}
## Environment Requirements
{Development and runtime requirements}
## Open Questions
{Unknowns needing resolution}
## Known Issues
Emergent blockers and issues discovered during execution. Add items here as flights surface problems that affect the broader mission — things not anticipated during planning but visible at the mission level.
- [ ] {Issue description} — discovered in Flight {N}, affects {scope}
## Flights
> **Note:** These are tentative suggestions, not commitments. Flights are planned and created one at a time as work progresses. This list will evolve based on discoveries during implementation.
- [ ] Flight 1: {description}
```
---
### Flight → Story
| Field | Mapping |
|-------|---------|
| Summary | Flight title |
| Description | See format below |
| Epic Link | Parent mission epic |
| Labels | `flight-control`, `flight` |
**Description Format:**
```
## Objective
{What this flight accomplishes}
## Contributing to Criteria
- {Relevant success criterion 1}
- {Relevant success criterion 2}
## Design Decisions
{Key technical decisions and rationale}
## Prerequisites
- [ ] {What must be true before execution}
## Technical Approach
{How the objective will be achieved}
## Legs
> **Note:** These are tentative suggestions, not commitments. Legs are planned and created one at a time as the flight progresses. This list will evolve based on discoveries during implementation.
- [ ] {leg-slug} - {description}
## Validation Approach
{How will this flight be validated? Manual testing, automated tests, or both?}
## Verification
{How to confirm success}
```
---
### Leg → Sub-task
| Field | Mapping |
|-------|---------|
| Summary | Leg title |
| Description | See format below |
| Parent | Flight story |
| Labels | `flight-control`, `leg` |
**Description Format:**
```
## Objective
{Single sentence: what this leg accomplishes}
## Context
{Design decisions and learnings from prior legs}
## Inputs
{What must exist before this leg runs}
## Outputs
{What exists after completion}
## Acceptance Criteria
- [ ] {Criterion 1}
- [ ] {Criterion 2}
## Verification Steps
How to confirm each criterion is met:
- {Command or manual check for criterion 1}
- {Command or manual check for criterion 2}
## Implementation Guidance
{Step-by-step guidance}
## Files Affected
{List of files to modify}
```
---
## Supporting Artifacts
### Flight Log → Story Comments
| Property | Value |
|----------|-------|
| Location | Comments on the Flight (Story) |
| Format | Timestamped comments with prefix |
| Update pattern | Append new comments during execution |
**Comment Format:**
```
[Flight Log] {YYYY-MM-DD HH:MM}
## {Entry Type}: {Title}
{Content based on entry type - see below}
```
**Entry Types:**
- `Leg Progress` - Status updates for leg completion
- `Decision` - Runtime decisions not in original plan
- `Deviation` - Departures from planned approach
- `Anomaly` - Unexpected issues encountered
- `Session Notes` - General progress notes
---
### Flight Briefing → Story Comment
| Property | Value |
|----------|-------|
| Location | Comment on the Flight (Story) |
| Created | Before flight execution begins |
| Label | `[Flight Briefing]` |
**Comment Format:**
```
[Flight Briefing] {YYYY-MM-DD}
## Mission Context
{How this flight contributes to mission}
## Objective
{What this flight will accomplish}
## Key Decisions
{Critical decisions crew should know}
## Risks
| Risk | Mitigation |
|------|------------|
| {risk} | {mitigation} |
## Legs Overview
1. {leg} - {description}
2. {leg} - {description}
## Success Criteria
{How we'll know the flight succeeded}
```
---
### Flight Debrief → Story Comment
| Property | Value |
|----------|-------|
| Location | Comment on the Flight (Story) |
| Created | After flight lands or diverts |
| Label | `[Flight Debrief]` |
**Comment Format:**
```
[Flight Debrief] {YYYY-MM-DD}
**Status**: {landed | aborted}
**Duration**: {start} - {end}
**Legs Completed**: {X of Y}
## Outcome Assessment
{What the flight accomplished}
## What Went Well
{Effective patterns}
## What Could Be Improved
{Recommendations}
## Deviations
| Deviation | Reason | Standardize? |
|-----------|--------|--------------|
| {what} | {why} | {yes/no} |
## Key Learnings
{Insights for future flights}
## Recommendations
1. {Most impactful recommendation}
2. {Second recommendation}
3. {Third recommendation}
## Action Items
- [ ] {action}
```
---
### Mission Debrief → Epic Comment
| Property | Value |
|----------|-------|
| Location | Comment on the Mission (Epic) |
| Created | After mission completes or aborts |
| Label | `[Mission Debrief]` |
**Comment Format:**
```
[Mission Debrief] {YYYY-MM-DD}
**Status**: {completed | aborted}
**Duration**: {start} - {end}
**Flights Completed**: {X of Y}
## Success Criteria Results
| Criterion | Status | Notes |
|-----------|--------|-------|
| {criterion} | {met/not met} | {notes} |
## Flight Summary
| Flight | Status | Outcome |
|--------|--------|---------|
| {flight} | {status} | {outcome} |
## What Went Well
{Successes}
## What Could Be Improved
{Improvements}
## Lessons Learned
{Insights}
## Action Items
- [ ] {action}
```
---
## State Mapping
### Mission (Epic)
| Flight Control | Jira Status |
|----------------|-------------|
| planning | To Do |
| active | In Progress |
| completed | Done |
| aborted | Cancelled |
### Flight (Story)
| Flight Control | Jira Status |
|----------------|-------------|
| planning | To Do |
| ready | Ready |
| in-flight | In Progress |
| landed | In Review |
| completed | Done |
| aborted | Cancelled |
### Leg (Sub-task)
| Flight Control | Jira Status |
|----------------|-------------|
| planning | To Do |
| ready | Ready |
| in-flight | In Progress |
| landed | In Review |
| completed | Done |
| aborted | Cancelled |
---
## Conventions
- **Naming**: Use clear, action-oriented summaries
- **Linking**: Always link Stories to Epic, Sub-tasks to Story
- **Labels**: Apply `flight-control` label to all artifacts
- **Immutability**: Never modify Sub-tasks once In Progress; create new ones
- **Comments**: Use prefixes (`[Flight Log]`, `[Flight Briefing]`, etc.) for filtering
## Git Workflow
| Property | Value |
|----------|-------|
| Strategy | `branch` |
**Options:**
- **`branch`** (default) — Single-checkout workflow. The orchestrator creates a feature branch and all agents work in the project root. One flight at a time per working copy.
- **`worktree`** — Worktree isolation. The orchestrator creates a git worktree under `.worktrees/` for each flight. Agents work in the worktree path. Parallel flights are possible on a single repo clone.
When using the `worktree` strategy, add `.worktrees/` to `.gitignore`.