diff --git a/agents/nelson.md b/agents/nelson.md index 0596569..73b05bf 100644 --- a/agents/nelson.md +++ b/agents/nelson.md @@ -1,6 +1,6 @@ --- name: nelson -description: England expects every agent to do its duty +description: Coordinates multi-agent work using Royal Navy squadron patterns with sailing orders, risk-tiered quality gates, and a captain's log. --- # Nelson diff --git a/scripts/check-references.sh b/scripts/check-references.sh index 99b6f53..503eea1 100755 --- a/scripts/check-references.sh +++ b/scripts/check-references.sh @@ -11,65 +11,36 @@ error() { } # ---------- 1. SKILL.md → references ---------- -# Every backtick-quoted path in MUST read/consult/use directives +# Every backtick-quoted references/ path in SKILL.md must exist echo "Checking SKILL.md → reference files..." while IFS= read -r path; do if [ ! -f "$SKILL_DIR/$path" ]; then error "SKILL.md references '$path' but $SKILL_DIR/$path does not exist" fi -# Case-insensitive: match "MUST" regardless of markdown emphasis -done < <(grep -Ei 'MUST (read|consult|use|read and apply)' "$SKILL_DIR/SKILL.md" \ - | grep -oE '`references/[^`]+`' \ +done < <(grep -oE '`references/[^`]+\.md`' "$SKILL_DIR/SKILL.md" \ | tr -d '`' \ | sort -u) -# ---------- 2. Index → sub-files ---------- -# Each index file's backtick-quoted .md paths must resolve -for index in admiralty-templates standing-orders damage-control; do - index_file="$REF_DIR/$index.md" - if [ ! -f "$index_file" ]; then - error "Index file $index_file does not exist" - continue - fi - - echo "Checking $index.md → sub-files..." - while IFS= read -r path; do - if [ ! -f "$REF_DIR/$path" ]; then - error "$index.md references '$path' but $REF_DIR/$path does not exist" - fi - done < <(grep -oE "\`${index}/[^\`]+\.md\`" "$index_file" \ - | tr -d '`' \ - | sort -u) -done - -# ---------- 3. Sub-file → index (orphan check) ---------- -# Every .md in a sub-directory must be listed in its parent index -for index in admiralty-templates standing-orders damage-control; do - index_file="$REF_DIR/$index.md" - subdir="$REF_DIR/$index" - [ -d "$subdir" ] || continue - - echo "Checking for orphans in $index/..." - for file in "$subdir"/*.md; do - # Skip if glob matched no files (bash returns literal pattern) +# ---------- 2. Subdirectory orphan check ---------- +# Every .md in a subdirectory must be referenced somewhere in SKILL.md +echo "Checking for orphaned subdirectory files..." +for subdir in admiralty-templates standing-orders damage-control; do + [ -d "$REF_DIR/$subdir" ] || continue + for file in "$REF_DIR/$subdir"/*.md; do [ -f "$file" ] || continue basename=$(basename "$file") - if ! grep -qE "\`${index}/${basename}\`" "$index_file"; then - error "$index/$basename exists on disk but is not listed in $index.md" + if ! grep -qE "\`references/${subdir}/${basename}\`" "$SKILL_DIR/SKILL.md"; then + error "$subdir/$basename exists on disk but is not referenced in SKILL.md" fi done done -# ---------- 4. Reference file cross-refs ---------- -# Backtick-quoted paths in non-index reference files +# ---------- 3. Reference file cross-refs ---------- +# Backtick-quoted paths in top-level reference files echo "Checking cross-references in reference files..." for ref_file in "$REF_DIR"/*.md; do [ -f "$ref_file" ] || continue basename=$(basename "$ref_file") - # Skip index files (they are validated in Section 2) - case "$basename" in - admiralty-templates.md|standing-orders.md|damage-control.md) continue ;; - esac # Paths like `references/foo.md` (relative to skill root) while IFS= read -r path; do @@ -90,7 +61,7 @@ for ref_file in "$REF_DIR"/*.md; do | sort -u) done -# ---------- 5. Subdirectory file cross-refs ---------- +# ---------- 4. Subdirectory file cross-refs ---------- # Backtick-quoted paths in subdirectory files echo "Checking cross-references in subdirectory files..." for subdir in admiralty-templates standing-orders damage-control; do @@ -119,19 +90,15 @@ for subdir in admiralty-templates standing-orders damage-control; do done done -# ---------- 6. Reverse orphan check ---------- -# Every top-level .md in references/ should be referenced by a MUST directive in SKILL.md +# ---------- 5. Reverse orphan check ---------- +# Every top-level .md in references/ should be referenced by SKILL.md echo "Checking for unreferenced top-level reference files..." for ref_file in "$REF_DIR"/*.md; do [ -f "$ref_file" ] || continue basename=$(basename "$ref_file") - # Skip index files (their sub-files are already checked in Section 2) - case "$basename" in - admiralty-templates.md|standing-orders.md|damage-control.md) continue ;; - esac if ! grep -qE "\`references/${basename}\`" "$SKILL_DIR/SKILL.md"; then - error "$basename exists in references/ but is not referenced by any MUST directive in SKILL.md" + error "$basename exists in references/ but is not referenced in SKILL.md" fi done diff --git a/skills/nelson/SKILL.md b/skills/nelson/SKILL.md index 23d0602..e01b3d0 100644 --- a/skills/nelson/SKILL.md +++ b/skills/nelson/SKILL.md @@ -1,6 +1,7 @@ --- name: nelson -description: Command a Royal Navy agent squadron from sailing orders through execution and stand-down. Use when work can be parallelized, requires tight coordination, or needs explicit action-station controls, quality gates, and a final captain's log. +description: Commands a Royal Navy agent squadron from sailing orders through execution and stand-down. Use when work can be parallelized, requires tight coordination, or needs explicit action-station controls, quality gates, and a final captain's log. +argument-hint: "[mission description]" --- # Nelson @@ -14,7 +15,7 @@ Execute this workflow for the user's mission. - Define what is out of scope. - Define stop criteria and required handoff artifacts. -You MUST read `references/admiralty-templates.md` and use the sailing-orders template when the user does not provide structure. +You MUST read `references/admiralty-templates/sailing-orders.md` and use the sailing-orders template when the user does not provide structure. ## 2. Form The Squadron @@ -29,11 +30,11 @@ You MUST read `references/admiralty-templates.md` and use the sailing-orders tem - Do not exceed 10 squadron-level agents (admiral, captains, red-cell navigator). Crew are additional. - Assign each captain a ship name from `references/crew-roles.md` matching task weight (frigate for general, destroyer for high-risk, patrol vessel for small, flagship for critical-path, submarine for research). - Captain decides crew composition per ship using the crew-or-direct decision tree in `references/crew-roles.md`. -- Captains may also deploy Royal Marines during execution for short-lived sorties — see `references/royal-marines.md`. +- Captains may also deploy Royal Marines during execution for short-lived sorties — see `references/royal-marines.md` and use `references/admiralty-templates/marine-deployment-brief.md` for the deployment brief. You MUST read `references/squadron-composition.md` for selection rules. You MUST read `references/crew-roles.md` for ship naming and crew composition. -You MUST consult `references/standing-orders.md` before forming the squadron. +You MUST consult the Standing Orders table below before forming the squadron. ## 3. Draft Battle Plan @@ -43,12 +44,13 @@ You MUST consult `references/standing-orders.md` before forming the squadron. - Keep one task in progress per agent unless the mission explicitly requires multitasking. - For each captain's task, include a ship manifest. If crew are mustered, list crew roles with sub-tasks and sequence. If the captain implements directly (0 crew), note "Captain implements directly." If the captain anticipates needing marine support, note marine capacity in the ship manifest (max 2). -You MUST read `references/admiralty-templates.md` for the battle plan and ship manifest template. -You MUST consult `references/standing-orders.md` when assigning files or if scope is unclear. +You MUST read `references/admiralty-templates/battle-plan.md` for the battle plan template. +You MUST read `references/admiralty-templates/ship-manifest.md` for the ship manifest template. +You MUST consult the Standing Orders table below when assigning files or if scope is unclear. **Before proceeding to Step 4:** Verify sailing orders exist, squadron is formed, and every task has an owner, deliverable, and action station tier. -**Crew Briefing:** When spawning each teammate via `Task()`, you MUST include a crew briefing using the template from `references/admiralty-templates.md`. Teammates do NOT inherit the lead's conversation context — they start with a clean slate and need explicit mission context to operate independently. +**Crew Briefing:** When spawning each teammate via `Task()`, you MUST include a crew briefing using the template from `references/admiralty-templates/crew-briefing.md`. Teammates do NOT inherit the lead's conversation context — they start with a clean slate and need explicit mission context to operate independently. ## 4. Run Quarterdeck Rhythm @@ -61,10 +63,10 @@ You MUST consult `references/standing-orders.md` when assigning files or if scop - Check for active marine deployments; verify marines have returned and outputs are incorporated. - Track burn against token/time budget. - Re-scope early when a task drifts from mission metric. -- When a mission encounters difficulties, you MUST consult `references/damage-control.md` for recovery and escalation procedures. +- When a mission encounters difficulties, you MUST consult the Damage Control table below for recovery and escalation procedures. -You MUST use `references/admiralty-templates.md` for the quarterdeck report template. -You MUST consult `references/standing-orders.md` if admiral is doing implementation or tasks are drifting from scope. +You MUST use `references/admiralty-templates/quarterdeck-report.md` for the quarterdeck report template. +You MUST consult the Standing Orders table below if admiral is doing implementation or tasks are drifting from scope. You MUST use `references/commendations.md` for recognition signals and graduated correction. ## 5. Set Action Stations @@ -78,10 +80,11 @@ You MUST use `references/commendations.md` for recognition signals and graduated - Task completion. - Agent idle with unverified outputs. - Before final synthesis. -- For crewed tasks, verify crew outputs align with role boundaries (consult `references/crew-roles.md` and `references/standing-orders.md` if role violations are detected). +- For crewed tasks, verify crew outputs align with role boundaries (consult `references/crew-roles.md` and the Standing Orders table below if role violations are detected). - Marine deployments follow station-tier rules in `references/royal-marines.md`. Station 2+ marine deployments require admiral approval. -You MUST consult `references/standing-orders.md` if tasks lack a tier or red-cell is assigned implementation work. +You MUST read `references/admiralty-templates/red-cell-review.md` for the red-cell review template. +You MUST consult the Standing Orders table below if tasks lack a tier or red-cell is assigned implementation work. ## 6. Stand Down And Log Action @@ -94,9 +97,41 @@ You MUST consult `references/standing-orders.md` if tasks lack a tier or red-cel - Mentioned in Despatches: name agents and contributions that were exemplary. - Record reusable patterns and failure modes for future missions. -You MUST use `references/admiralty-templates.md` for the captain's log template. +You MUST use `references/admiralty-templates/captains-log.md` for the captain's log template. You MUST use `references/commendations.md` for Mentioned in Despatches criteria. +## Standing Orders + +Consult the specific standing order that matches the situation. + +| Situation | Standing Order | +|---|---| +| Choosing between single-session and multi-agent | `references/standing-orders/becalmed-fleet.md` | +| Deciding whether to add another agent | `references/standing-orders/crew-without-canvas.md` | +| Assigning files to agents in the battle plan | `references/standing-orders/split-keel.md` | +| Task scope drifting from sailing orders | `references/standing-orders/drifting-anchorage.md` | +| Admiral doing implementation instead of coordinating | `references/standing-orders/admiral-at-the-helm.md` | +| Assigning work to the red-cell navigator | `references/standing-orders/press-ganged-navigator.md` | +| Tasks proceeding without a risk tier classification | `references/standing-orders/unclassified-engagement.md` | +| Captain implementing instead of coordinating crew | `references/standing-orders/captain-at-the-capstan.md` | +| Crewing every role regardless of task needs | `references/standing-orders/all-hands-on-deck.md` | +| Spawning one crew member for an atomic task | `references/standing-orders/skeleton-crew.md` | +| Assigning crew work outside their role | `references/standing-orders/pressed-crew.md` | +| Captain deploying marines for crew work or sustained tasks | `references/standing-orders/battalion-ashore.md` | + +## Damage Control + +Consult the specific procedure that matches the situation. + +| Situation | Procedure | +|---|---| +| Agent unresponsive, looping, or producing no useful output | `references/damage-control/man-overboard.md` | +| Session interrupted (context limit, crash, timeout) | `references/damage-control/session-resumption.md` | +| Completed task found faulty, other tasks are sound | `references/damage-control/partial-rollback.md` | +| Mission cannot succeed, continuing wastes budget | `references/damage-control/scuttle-and-reform.md` | +| Issue exceeds current authority or needs clarification | `references/damage-control/escalation.md` | +| Ship's crew consuming disproportionate tokens or time | `references/damage-control/crew-overrun.md` | + ## Admiralty Doctrine - Optimize for mission throughput, not equal work distribution. diff --git a/skills/nelson/references/action-stations.md b/skills/nelson/references/action-stations.md index 45039ee..7eb0bf1 100644 --- a/skills/nelson/references/action-stations.md +++ b/skills/nelson/references/action-stations.md @@ -2,6 +2,16 @@ Classify each task before execution. Apply the minimum required controls. +## Contents + +- [Station 0: Patrol](#station-0-patrol) +- [Station 1: Caution](#station-1-caution) +- [Station 2: Action](#station-2-action) +- [Station 3: Trafalgar](#station-3-trafalgar) +- [Risk Classification Decision Tree](#risk-classification-decision-tree) +- [Failure-Mode Checklist](#failure-mode-checklist) +- [Marine Deployments](#marine-deployments) + ## Station 0: Patrol Criteria: diff --git a/skills/nelson/references/admiralty-templates.md b/skills/nelson/references/admiralty-templates.md deleted file mode 100644 index 53430b8..0000000 --- a/skills/nelson/references/admiralty-templates.md +++ /dev/null @@ -1,14 +0,0 @@ -# Templates - -Consult the specific template for the current workflow step. - -| Step | Template | -|---|---| -| Issue Sailing Orders | `admiralty-templates/sailing-orders.md` | -| Draft Battle Plan | `admiralty-templates/battle-plan.md` | -| Captain crews a ship | `admiralty-templates/ship-manifest.md` | -| Run Quarterdeck Rhythm | `admiralty-templates/quarterdeck-report.md` | -| Set Action Stations (red-cell review) | `admiralty-templates/red-cell-review.md` | -| Brief crew for dispatch | `admiralty-templates/crew-briefing.md` | -| Deploy marines from a ship | `admiralty-templates/marine-deployment-brief.md` | -| Stand Down And Log Action | `admiralty-templates/captains-log.md` | diff --git a/skills/nelson/references/damage-control.md b/skills/nelson/references/damage-control.md deleted file mode 100644 index 4d53235..0000000 --- a/skills/nelson/references/damage-control.md +++ /dev/null @@ -1,12 +0,0 @@ -# Damage Control - -Consult the specific procedure that matches the situation. - -| Situation | Procedure | -|---|---| -| Agent unresponsive, looping, or producing no useful output | `damage-control/man-overboard.md` | -| Session interrupted (context limit, crash, timeout) | `damage-control/session-resumption.md` | -| Completed task found faulty, other tasks are sound | `damage-control/partial-rollback.md` | -| Mission cannot succeed, continuing wastes budget | `damage-control/scuttle-and-reform.md` | -| Issue exceeds current authority or needs clarification | `damage-control/escalation.md` | -| Ship's crew consuming disproportionate tokens or time | `damage-control/crew-overrun.md` | diff --git a/skills/nelson/references/squadron-composition.md b/skills/nelson/references/squadron-composition.md index 17f73ae..510306c 100644 --- a/skills/nelson/references/squadron-composition.md +++ b/skills/nelson/references/squadron-composition.md @@ -37,4 +37,4 @@ Choose the first condition that matches. ## Anti-Patterns -See `references/standing-orders.md` for the full list of standing orders and known anti-patterns. +See the Standing Orders table in SKILL.md for the full list of standing orders and known anti-patterns. diff --git a/skills/nelson/references/standing-orders.md b/skills/nelson/references/standing-orders.md deleted file mode 100644 index a856598..0000000 --- a/skills/nelson/references/standing-orders.md +++ /dev/null @@ -1,18 +0,0 @@ -# Standing Orders - -Consult the specific standing order that matches the situation. - -| Situation | Standing Order | -|---|---| -| Choosing between single-session and multi-agent | `standing-orders/becalmed-fleet.md` | -| Deciding whether to add another agent | `standing-orders/crew-without-canvas.md` | -| Assigning files to agents in the battle plan | `standing-orders/split-keel.md` | -| Task scope drifting from sailing orders | `standing-orders/drifting-anchorage.md` | -| Admiral doing implementation instead of coordinating | `standing-orders/admiral-at-the-helm.md` | -| Assigning work to the red-cell navigator | `standing-orders/press-ganged-navigator.md` | -| Tasks proceeding without a risk tier classification | `standing-orders/unclassified-engagement.md` | -| Captain implementing instead of coordinating crew | `standing-orders/captain-at-the-capstan.md` | -| Crewing every role regardless of task needs | `standing-orders/all-hands-on-deck.md` | -| Spawning one crew member for an atomic task | `standing-orders/skeleton-crew.md` | -| Assigning crew work outside their role | `standing-orders/pressed-crew.md` | -| Captain deploying marines for crew work or sustained tasks | `standing-orders/battalion-ashore.md` |