From 365729783f3691c842fc16d4c6c9032bca4e6254 Mon Sep 17 00:00:00 2001 From: harrymunro Date: Fri, 20 Feb 2026 21:44:34 -0400 Subject: [PATCH] Deliver all Phase 1-3 skill improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add 17 new features across three phases, covering damage control, standing orders, templates, core patterns, ecosystem tooling, and quality gates. Integrate all references into SKILL.md with a new Quick Start section, Ecosystem section, and expanded tables. Phase 1 — Quick Wins: - Quick Start mode in SKILL.md - Material Conditions (XRAY/YOKE/ZEBRA) replacing Green/Amber/Red - Soundings proactive budget cliff detection - Quarterdeck report headline format redesign - Standing order troubleshooter decision tree Phase 2 — Core Enhancements: - Eight new standing orders (anti-patterns and tactics) - Dynamic task ledger (Magentic-One living battle plan) - Colours Struck graceful degradation procedure - Sailing orders wizard interactive guide - Captain's log plan-vs-reality redesign Phase 3 — Ecosystem & Tooling: - Event-driven hooks for automated damage control - Red-cell challenge library with domain failure patterns - Companion plugin ecosystem specification - Squadron metrics framework (6 RN-themed metrics) - Bulkhead doctrine cascading failure containment - Broadside synchronised quality gates - Cutting the line blocking bypass tactic --- .beans.yml | 6 + ...g--dynamic-task-ledger-magentic-pattern.md | 14 ++ ...ndings-proactive-budget-cliff-detection.md | 14 ++ .../nelson-4iqy--phase-3-ecosystem-tooling.md | 13 ++ .../nelson-79a0--eight-new-standing-orders.md | 14 ++ ...terdeck-report-redesign-headline-format.md | 14 ++ ...iven-hooks-for-automated-damage-control.md | 14 ++ .../nelson-bx89--phase-2-core-enhancements.md | 13 ++ ...elson-duw6--quick-start-mode-in-skillmd.md | 14 ++ ...--captains-log-plan-vs-reality-redesign.md | 14 ++ ...p--broadside-synchronised-quality-gates.md | 14 ++ ...nditions-xrayyokezebra-for-hull-integri.md | 14 ++ ...ontextual-standing-order-troubleshooter.md | 14 ++ ...s-struck-graceful-degradation-procedure.md | 14 ++ ...-doctrine-cascading-failure-containment.md | 14 ++ ...nelson-sl49--companion-plugin-ecosystem.md | 14 ++ ...he-line-bypassing-blocking-dependencies.md | 14 ++ ...wt1--metrics-framework-squadron-metrics.md | 14 ++ .beans/nelson-vzbj--sailing-orders-wizard.md | 14 ++ ...nelson-xrln--red-cell-challenge-library.md | 14 ++ .beans/nelson-yfhj--phase-1-quick-wins.md | 13 ++ CLAUDE.md | 51 +++++++- skills/nelson/SKILL.md | 43 +++++- .../admiralty-templates/captains-log.md | 25 ++++ .../admiralty-templates/quarterdeck-report.md | 58 +++++---- .../references/broadside-quality-gates.md | 59 +++++++++ skills/nelson/references/companion-plugins.md | 111 ++++++++++++++++ .../damage-control/bulkhead-doctrine.md | 66 ++++++++++ .../damage-control/colours-struck.md | 69 ++++++++++ .../damage-control/hull-integrity.md | 50 ++++--- .../references/damage-control/soundings.md | 83 ++++++++++++ .../nelson/references/dynamic-task-ledger.md | 70 ++++++++++ .../nelson/references/event-driven-hooks.md | 122 ++++++++++++++++++ .../references/red-cell-challenge-library.md | 60 +++++++++ .../references/sailing-orders-wizard.md | 102 +++++++++++++++ skills/nelson/references/squadron-metrics.md | 113 ++++++++++++++++ .../standing-order-troubleshooter.md | 64 +++++++++ .../references/standing-orders/chain-break.md | 10 ++ .../standing-orders/circular-tides.md | 10 ++ .../standing-orders/crossing-signals.md | 10 ++ .../standing-orders/cutting-the-line.md | 10 ++ .../standing-orders/fraying-tether.md | 10 ++ .../references/standing-orders/ghost-crews.md | 10 ++ .../standing-orders/silent-watch.md | 10 ++ .../references/standing-orders/storm-surge.md | 10 ++ .../references/standing-orders/tidal-pull.md | 10 ++ 46 files changed, 1472 insertions(+), 47 deletions(-) create mode 100644 .beans.yml create mode 100644 .beans/nelson-2s6g--dynamic-task-ledger-magentic-pattern.md create mode 100644 .beans/nelson-3lax--soundings-proactive-budget-cliff-detection.md create mode 100644 .beans/nelson-4iqy--phase-3-ecosystem-tooling.md create mode 100644 .beans/nelson-79a0--eight-new-standing-orders.md create mode 100644 .beans/nelson-7be5--quarterdeck-report-redesign-headline-format.md create mode 100644 .beans/nelson-bvad--event-driven-hooks-for-automated-damage-control.md create mode 100644 .beans/nelson-bx89--phase-2-core-enhancements.md create mode 100644 .beans/nelson-duw6--quick-start-mode-in-skillmd.md create mode 100644 .beans/nelson-dxcy--captains-log-plan-vs-reality-redesign.md create mode 100644 .beans/nelson-fcgp--broadside-synchronised-quality-gates.md create mode 100644 .beans/nelson-l566--material-conditions-xrayyokezebra-for-hull-integri.md create mode 100644 .beans/nelson-qqqh--contextual-standing-order-troubleshooter.md create mode 100644 .beans/nelson-rrci--colours-struck-graceful-degradation-procedure.md create mode 100644 .beans/nelson-sgzy--bulkhead-doctrine-cascading-failure-containment.md create mode 100644 .beans/nelson-sl49--companion-plugin-ecosystem.md create mode 100644 .beans/nelson-swtq--cutting-the-line-bypassing-blocking-dependencies.md create mode 100644 .beans/nelson-vwt1--metrics-framework-squadron-metrics.md create mode 100644 .beans/nelson-vzbj--sailing-orders-wizard.md create mode 100644 .beans/nelson-xrln--red-cell-challenge-library.md create mode 100644 .beans/nelson-yfhj--phase-1-quick-wins.md create mode 100644 skills/nelson/references/broadside-quality-gates.md create mode 100644 skills/nelson/references/companion-plugins.md create mode 100644 skills/nelson/references/damage-control/bulkhead-doctrine.md create mode 100644 skills/nelson/references/damage-control/colours-struck.md create mode 100644 skills/nelson/references/damage-control/soundings.md create mode 100644 skills/nelson/references/dynamic-task-ledger.md create mode 100644 skills/nelson/references/event-driven-hooks.md create mode 100644 skills/nelson/references/red-cell-challenge-library.md create mode 100644 skills/nelson/references/sailing-orders-wizard.md create mode 100644 skills/nelson/references/squadron-metrics.md create mode 100644 skills/nelson/references/standing-order-troubleshooter.md create mode 100644 skills/nelson/references/standing-orders/chain-break.md create mode 100644 skills/nelson/references/standing-orders/circular-tides.md create mode 100644 skills/nelson/references/standing-orders/crossing-signals.md create mode 100644 skills/nelson/references/standing-orders/cutting-the-line.md create mode 100644 skills/nelson/references/standing-orders/fraying-tether.md create mode 100644 skills/nelson/references/standing-orders/ghost-crews.md create mode 100644 skills/nelson/references/standing-orders/silent-watch.md create mode 100644 skills/nelson/references/standing-orders/storm-surge.md create mode 100644 skills/nelson/references/standing-orders/tidal-pull.md diff --git a/.beans.yml b/.beans.yml new file mode 100644 index 0000000..ed92392 --- /dev/null +++ b/.beans.yml @@ -0,0 +1,6 @@ +beans: + path: .beans + prefix: nelson- + id_length: 4 + default_status: todo + default_type: task diff --git a/.beans/nelson-2s6g--dynamic-task-ledger-magentic-pattern.md b/.beans/nelson-2s6g--dynamic-task-ledger-magentic-pattern.md new file mode 100644 index 0000000..7ed7c32 --- /dev/null +++ b/.beans/nelson-2s6g--dynamic-task-ledger-magentic-pattern.md @@ -0,0 +1,14 @@ +--- +# nelson-2s6g +title: Dynamic Task Ledger (Magentic Pattern) +status: completed +type: feature +priority: high +created_at: 2026-02-21T01:19:01Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-bx89 +--- + +Adopt the living battle plan pattern from Microsoft's Magentic-One. The admiral continuously reprioritises tasks, updates dependencies, and communicates changes at each quarterdeck checkpoint. Formalise what good admirals already do informally. The battle plan becomes a living document that evolves with mission reality. Source: HMS Ambush (Coordination). Effort: Medium. Impact: Very High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-3lax--soundings-proactive-budget-cliff-detection.md b/.beans/nelson-3lax--soundings-proactive-budget-cliff-detection.md new file mode 100644 index 0000000..bb01376 --- /dev/null +++ b/.beans/nelson-3lax--soundings-proactive-budget-cliff-detection.md @@ -0,0 +1,14 @@ +--- +# nelson-3lax +title: Soundings — Proactive Budget Cliff Detection +status: completed +type: feature +priority: high +created_at: 2026-02-21T01:18:39Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-yfhj +--- + +Add proactive token budget monitoring every 5-10 turns. Check remaining context window percentage, calculate burn rate (tokens used in last N turns / N), estimate turns to Critical ((remaining context × 0.35) / burn rate), escalate to admiral if turns to Critical < 3. Prevents silent context exhaustion. Source: HMS Tirpitz (Resilience). Effort: Low. Impact: High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-4iqy--phase-3-ecosystem-tooling.md b/.beans/nelson-4iqy--phase-3-ecosystem-tooling.md new file mode 100644 index 0000000..3784766 --- /dev/null +++ b/.beans/nelson-4iqy--phase-3-ecosystem-tooling.md @@ -0,0 +1,13 @@ +--- +# nelson-4iqy +title: Phase 3 — Ecosystem & Tooling +status: completed +type: milestone +priority: normal +created_at: 2026-02-21T01:17:52Z +updated_at: 2026-02-21T01:42:31Z +--- + +Ongoing ecosystem expansion. Items: Event-driven hooks, Red-Cell Challenge Library, companion plugins, lightweight metrics, remaining standing orders and terminology. + +## Summary of Changes\n\nAll Phase 3 Ecosystem and Tooling delivered: Event-Driven Hooks, Red-Cell Challenge Library, Companion Plugins, Metrics Framework, Bulkhead Doctrine, Broadside Quality Gates, and Cutting the Line. diff --git a/.beans/nelson-79a0--eight-new-standing-orders.md b/.beans/nelson-79a0--eight-new-standing-orders.md new file mode 100644 index 0000000..6942e20 --- /dev/null +++ b/.beans/nelson-79a0--eight-new-standing-orders.md @@ -0,0 +1,14 @@ +--- +# nelson-79a0 +title: Eight New Standing Orders +status: completed +type: feature +priority: high +created_at: 2026-02-21T01:18:56Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-bx89 +--- + +Add eight new standing orders covering novel anti-patterns: Silent Watch (stale context), Crossing Signals (ambiguous orders), Circular Tides (circular dependencies/deadlock), Ghost Crews (duplicate work), Fraying Tether (silent quality degradation), Chain Break (authority ambiguity), Tidal Pull (memory loss across handoffs), Storm Surge (poor task decomposition). Each includes detection criteria, remedies, and example scenarios. Phase 2 prioritises Circular Tides, Storm Surge, Silent Watch, Ghost Crews. Source: HMS Audacious (Anti-Patterns). Effort: Medium. Impact: High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-7be5--quarterdeck-report-redesign-headline-format.md b/.beans/nelson-7be5--quarterdeck-report-redesign-headline-format.md new file mode 100644 index 0000000..8af4e16 --- /dev/null +++ b/.beans/nelson-7be5--quarterdeck-report-redesign-headline-format.md @@ -0,0 +1,14 @@ +--- +# nelson-7be5 +title: Quarterdeck Report Redesign — Headline Format +status: completed +type: feature +priority: high +created_at: 2026-02-21T01:18:42Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-yfhj +--- + +Replace the current flat quarterdeck report with a scannable headline format: one-line status, compact progress table, scoped blockers with owners and ETAs, single Admiral Decision line. Reduces checkpoint review from 3 minutes to 30 seconds. Source: HMS Anson (UX). Effort: Low. Impact: High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-bvad--event-driven-hooks-for-automated-damage-control.md b/.beans/nelson-bvad--event-driven-hooks-for-automated-damage-control.md new file mode 100644 index 0000000..e883e96 --- /dev/null +++ b/.beans/nelson-bvad--event-driven-hooks-for-automated-damage-control.md @@ -0,0 +1,14 @@ +--- +# nelson-bvad +title: Event-Driven Hooks for Automated Damage Control +status: completed +type: feature +priority: high +created_at: 2026-02-21T01:19:10Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-4iqy +--- + +Leverage Claude Code hooks (PreToolUse, PostToolUse, Stop) to automate damage control: token burn monitoring (auto-file damage reports at thresholds), idle crew detection (alert when crew member has no output in N turns), forced checkpoint prompts (inject quarterdeck rhythm reminders), auto-saving captain's logs (persist session state on Stop hook). Major reduction in admiral cognitive load. Source: HMS Artful (Plugin Ecosystem). Effort: Medium. Impact: High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-bx89--phase-2-core-enhancements.md b/.beans/nelson-bx89--phase-2-core-enhancements.md new file mode 100644 index 0000000..439a0ba --- /dev/null +++ b/.beans/nelson-bx89--phase-2-core-enhancements.md @@ -0,0 +1,13 @@ +--- +# nelson-bx89 +title: Phase 2 — Core Enhancements +status: completed +type: milestone +priority: normal +created_at: 2026-02-21T01:17:52Z +updated_at: 2026-02-21T01:42:31Z +--- + +Medium-effort improvements requiring 2-3 sessions. Items: New standing orders, Dynamic Task Ledger, Sailing Orders Wizard, Colours Struck degradation, Captain's Log redesign. + +## Summary of Changes\n\nAll Phase 2 Core Enhancements delivered: Eight New Standing Orders, Dynamic Task Ledger, Colours Struck, Sailing Orders Wizard, and Captain's Log Redesign. diff --git a/.beans/nelson-duw6--quick-start-mode-in-skillmd.md b/.beans/nelson-duw6--quick-start-mode-in-skillmd.md new file mode 100644 index 0000000..b0b47e1 --- /dev/null +++ b/.beans/nelson-duw6--quick-start-mode-in-skillmd.md @@ -0,0 +1,14 @@ +--- +# nelson-duw6 +title: Quick Start Mode in SKILL.md +status: completed +type: feature +priority: high +created_at: 2026-02-21T01:18:32Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-yfhj +--- + +Add a 60-second Quick Start section at the top of SKILL.md. Progressive disclosure approach: brief intro, minimal happy path, full reference below. First-time users currently face a wall of 6 steps, 13 cross-references, and 18 standing orders. Source: HMS Anson (UX). Effort: Low. Impact: High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-dxcy--captains-log-plan-vs-reality-redesign.md b/.beans/nelson-dxcy--captains-log-plan-vs-reality-redesign.md new file mode 100644 index 0000000..abb5bed --- /dev/null +++ b/.beans/nelson-dxcy--captains-log-plan-vs-reality-redesign.md @@ -0,0 +1,14 @@ +--- +# nelson-dxcy +title: Captain's Log Plan-vs-Reality Redesign +status: completed +type: feature +priority: normal +created_at: 2026-02-21T01:19:13Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-bx89 +--- + +Redesign the Captain's Log to capture plan-vs-reality delta. Compare what was planned at Battle Plan stage with what actually happened during execution. Track divergences, decision points, and lessons learned. Mentioned in Phase 2 roadmap of the improvement dossier. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-fcgp--broadside-synchronised-quality-gates.md b/.beans/nelson-fcgp--broadside-synchronised-quality-gates.md new file mode 100644 index 0000000..67cb15e --- /dev/null +++ b/.beans/nelson-fcgp--broadside-synchronised-quality-gates.md @@ -0,0 +1,14 @@ +--- +# nelson-fcgp +title: Broadside — Synchronised Quality Gates +status: completed +type: feature +priority: low +created_at: 2026-02-21T01:19:33Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-4iqy +--- + +Coordinated checkpoint where all ships submit validation evidence simultaneously. Admiral calls Broadside at pre-defined milestones. All ships pause and submit outputs with validation evidence. Red-cell reviews all outputs at once, checking cross-ship consistency and integration. Admiral makes single go/no-go decision. Valuable for Station 2+ work where integration failures are primary risk. Source: HMS Agamemnon (Terminology). Effort: Medium. Impact: Medium. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-l566--material-conditions-xrayyokezebra-for-hull-integri.md b/.beans/nelson-l566--material-conditions-xrayyokezebra-for-hull-integri.md new file mode 100644 index 0000000..c550f17 --- /dev/null +++ b/.beans/nelson-l566--material-conditions-xrayyokezebra-for-hull-integri.md @@ -0,0 +1,14 @@ +--- +# nelson-l566 +title: Material Conditions (XRAY/YOKE/ZEBRA) for Hull Integrity +status: completed +type: feature +priority: high +created_at: 2026-02-21T01:18:36Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-yfhj +--- + +Replace abstract Green/Amber/Red hull integrity labels with authentic Royal Navy material conditions. Condition XRAY (routine cruising, all compartments open), Condition YOKE (heightened readiness, non-essential compartments secured), Condition ZEBRA (action stations, maximum watertight integrity). Each condition has specific closure rules mapping to context window management states. Source: HMS Agamemnon (Terminology). Effort: Low. Impact: High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-qqqh--contextual-standing-order-troubleshooter.md b/.beans/nelson-qqqh--contextual-standing-order-troubleshooter.md new file mode 100644 index 0000000..be267aa --- /dev/null +++ b/.beans/nelson-qqqh--contextual-standing-order-troubleshooter.md @@ -0,0 +1,14 @@ +--- +# nelson-qqqh +title: Contextual Standing Order Troubleshooter +status: completed +type: feature +priority: normal +created_at: 2026-02-21T01:18:45Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-yfhj +--- + +Add a contextual troubleshooter that helps identify which standing order applies to a given situation. Mentioned in the Phase 1 roadmap of the improvement dossier. Source: Implementation Roadmap. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-rrci--colours-struck-graceful-degradation-procedure.md b/.beans/nelson-rrci--colours-struck-graceful-degradation-procedure.md new file mode 100644 index 0000000..2fb9e93 --- /dev/null +++ b/.beans/nelson-rrci--colours-struck-graceful-degradation-procedure.md @@ -0,0 +1,14 @@ +--- +# nelson-rrci +title: Colours Struck — Graceful Degradation Procedure +status: completed +type: feature +priority: high +created_at: 2026-02-21T01:19:09Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-bx89 +--- + +Add a graceful degradation procedure between full success and full abort. At each checkpoint, classify remaining tasks as Mission Critical (MVP), High Value (nice to have), or Polish (non-essential). Admiral can stage degraded delivery: Full Degradation (only Mission Critical), Staged Degradation (Mission Critical + partial High Value), or Abort (existing scuttle). Produce a degraded capability report. Source: HMS Tirpitz (Resilience). Effort: Medium. Impact: High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-sgzy--bulkhead-doctrine-cascading-failure-containment.md b/.beans/nelson-sgzy--bulkhead-doctrine-cascading-failure-containment.md new file mode 100644 index 0000000..72318aa --- /dev/null +++ b/.beans/nelson-sgzy--bulkhead-doctrine-cascading-failure-containment.md @@ -0,0 +1,14 @@ +--- +# nelson-sgzy +title: Bulkhead Doctrine — Cascading Failure Containment +status: completed +type: feature +priority: normal +created_at: 2026-02-21T01:19:30Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-4iqy +--- + +Allocate separate token budgets per ship in the battle plan. Each ship gets an explicit token allocation based on task complexity. Admiral holds a 15-20% reserve pool for relief operations and emergencies. If 3+ ships reach Red hull integrity simultaneously, pause all new work and escalate. Downstream tasks don't proceed if upstream dependency is in Red. Prevents cascading resource consumption. Source: HMS Tirpitz (Resilience). Effort: Medium-High. Impact: High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-sl49--companion-plugin-ecosystem.md b/.beans/nelson-sl49--companion-plugin-ecosystem.md new file mode 100644 index 0000000..8a6472c --- /dev/null +++ b/.beans/nelson-sl49--companion-plugin-ecosystem.md @@ -0,0 +1,14 @@ +--- +# nelson-sl49 +title: Companion Plugin Ecosystem +status: completed +type: feature +priority: normal +created_at: 2026-02-21T01:19:17Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-4iqy +--- + +Expand marketplace to distribute companion plugins: nelson-templates (pre-built battle plans for common scenarios), nelson-crew-library (organisation-specific crew roles and standing orders), nelson-integrations (hooks for Jira, GitHub Projects, Slack), nelson-metrics (dashboard generation from captain's logs). Keep core lean while enabling rich extensibility. Source: HMS Artful (Plugin Ecosystem). Effort: Medium. Impact: Medium-High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-swtq--cutting-the-line-bypassing-blocking-dependencies.md b/.beans/nelson-swtq--cutting-the-line-bypassing-blocking-dependencies.md new file mode 100644 index 0000000..11f1ab4 --- /dev/null +++ b/.beans/nelson-swtq--cutting-the-line-bypassing-blocking-dependencies.md @@ -0,0 +1,14 @@ +--- +# nelson-swtq +title: Cutting the Line — Bypassing Blocking Dependencies +status: completed +type: feature +priority: low +created_at: 2026-02-21T01:19:26Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-4iqy +--- + +Named after Nelson's Trafalgar tactic. When a blocking task is low priority but holds up a high-value dependent, the captain requests permission to cut the line: proceed in parallel, accept explicit rework risk, require admiral approval, red-cell reviews the risk assessment. Source: HMS Agamemnon (Terminology). Effort: Low. Impact: Medium. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-vwt1--metrics-framework-squadron-metrics.md b/.beans/nelson-vwt1--metrics-framework-squadron-metrics.md new file mode 100644 index 0000000..7c00cc7 --- /dev/null +++ b/.beans/nelson-vwt1--metrics-framework-squadron-metrics.md @@ -0,0 +1,14 @@ +--- +# nelson-vwt1 +title: Metrics Framework — Squadron Metrics +status: completed +type: feature +priority: normal +created_at: 2026-02-21T01:19:20Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-4iqy +--- + +Implement six metric categories with RN-themed names: Homecoming Rate (mission success %), Coal Consumption (tokens per completed task), Anchor to Sail (time to first output), Signal Clarity (blocker resolution speed), Dock Inspection (verification pass rate), Seaworthiness Index (average hull integrity at stand-down). Start with 5 lightweight metrics from existing template fields. No new tooling for Phase 1. Source: HMS Trafalgar (Metrics). Effort: Phased. Impact: Medium-High. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-vzbj--sailing-orders-wizard.md b/.beans/nelson-vzbj--sailing-orders-wizard.md new file mode 100644 index 0000000..908e32e --- /dev/null +++ b/.beans/nelson-vzbj--sailing-orders-wizard.md @@ -0,0 +1,14 @@ +--- +# nelson-vzbj +title: Sailing Orders Wizard +status: completed +type: feature +priority: normal +created_at: 2026-02-21T01:19:04Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-bx89 +--- + +Interactive scaffold guiding users through sailing order creation: What's the outcome? How will we know it worked? When does it need to be done? Any constraints? What's out of scope? Auto-populates template with sensible defaults and validates completeness. Source: HMS Anson (UX). Effort: Medium. Impact: Medium. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-xrln--red-cell-challenge-library.md b/.beans/nelson-xrln--red-cell-challenge-library.md new file mode 100644 index 0000000..535a9d6 --- /dev/null +++ b/.beans/nelson-xrln--red-cell-challenge-library.md @@ -0,0 +1,14 @@ +--- +# nelson-xrln +title: Red-Cell Challenge Library +status: completed +type: feature +priority: normal +created_at: 2026-02-21T01:19:13Z +updated_at: 2026-02-21T01:42:08Z +parent: nelson-4iqy +--- + +Seed red-cell reviews with domain-specific failure patterns instead of inventing them from scratch. Categories: Auth & Security (token expiry, privilege escalation, injection), Data Integrity (race conditions, partial writes, schema drift), API Design (breaking changes, pagination edge cases, rate limits), Infrastructure (DNS propagation, certificate expiry, connection pool exhaustion). Library grows with mission lessons learned. Source: HMS Anson (UX). Effort: Medium. Impact: Medium. + +## Summary of Changes\n\nDelivered as part of the full-fleet mission. All files created/modified and integrated into SKILL.md. diff --git a/.beans/nelson-yfhj--phase-1-quick-wins.md b/.beans/nelson-yfhj--phase-1-quick-wins.md new file mode 100644 index 0000000..5eced6b --- /dev/null +++ b/.beans/nelson-yfhj--phase-1-quick-wins.md @@ -0,0 +1,13 @@ +--- +# nelson-yfhj +title: Phase 1 — Quick Wins +status: completed +type: milestone +priority: high +created_at: 2026-02-21T01:17:52Z +updated_at: 2026-02-21T01:42:30Z +--- + +Low-effort, high-impact improvements deliverable in a single session. Items: Quick Start mode, Quarterdeck headline redesign, Material Conditions terminology, Soundings procedure, contextual standing order troubleshooter. + +## Summary of Changes\n\nAll Phase 1 Quick Wins delivered: Quick Start Mode, Material Conditions (XRAY/YOKE/ZEBRA), Quarterdeck Report Redesign, Soundings, and Contextual Standing Order Troubleshooter. diff --git a/CLAUDE.md b/CLAUDE.md index e339fa9..727e9b9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,17 +13,63 @@ skills/nelson/ references/ — Supporting docs loaded on demand action-stations.md — Risk tier definitions (Station 0–3) admiralty-templates/ — One file per template, loaded on demand + battle-plan.md — Task assignment template + captains-log.md — End-of-mission log with plan-vs-reality delta + crew-briefing.md — Teammate briefing template damage-report.md — JSON template for hull integrity damage reports + marine-deployment-brief.md — Royal Marines deployment brief + quarterdeck-report.md — Headline-format checkpoint report + red-cell-review.md — Red-cell review template + sailing-orders.md — Mission sailing orders template + ship-manifest.md — Ship crew manifest template turnover-brief.md — Handover brief for relief on station + broadside-quality-gates.md — Synchronised quality gates across all ships commendations.md — Recognition signals & graduated correction + companion-plugins.md — Companion plugin ecosystem specification crew-roles.md — Crew role definitions, ship names & sizing rules damage-control/ — One file per procedure, loaded on demand - hull-integrity.md — Threshold definitions & squadron readiness board + bulkhead-doctrine.md — Per-ship token budgets & cascading failure containment + colours-struck.md — Graceful degradation between success and abort + crew-overrun.md — Crew consuming disproportionate resources + escalation.md — Authority escalation procedure + hull-integrity.md — Material conditions (XRAY/YOKE/ZEBRA) & readiness board + man-overboard.md — Unresponsive or looping agent recovery + partial-rollback.md — Rolling back a single faulty task relief-on-station.md — Planned ship replacement for context exhaustion + scuttle-and-reform.md — Full mission abort and reform session-hygiene.md — Clean start procedure for new sessions + session-resumption.md — Resuming an interrupted session + soundings.md — Proactive budget cliff detection between checkpoints + dynamic-task-ledger.md — Living battle plan (Magentic-One pattern) + event-driven-hooks.md — Claude Code hooks for automated damage control + red-cell-challenge-library.md — Domain-specific failure patterns for reviews royal-marines.md — Royal Marines deployment rules & specialisations + sailing-orders-wizard.md — Interactive sailing order creation guide squadron-composition.md — Mode selection & team sizing rules + squadron-metrics.md — Six RN-themed performance metrics + standing-order-troubleshooter.md — Decision tree for identifying standing orders standing-orders/ — One file per anti-pattern, loaded on demand + admiral-at-the-helm.md — Admiral must not implement + all-hands-on-deck.md — Do not over-crew + battalion-ashore.md — Marines are not crew + becalmed-fleet.md — Do not parallelise sequential work + captain-at-the-capstan.md — Captain must not implement when crewed + chain-break.md — Authority ambiguity + circular-tides.md — Circular dependencies / deadlock + crew-without-canvas.md — Do not add unnecessary agents + crossing-signals.md — Ambiguous orders + cutting-the-line.md — Bypassing low-priority blockers (tactical) + drifting-anchorage.md — Scope drift from sailing orders + fraying-tether.md — Silent quality degradation + ghost-crews.md — Duplicate work across agents + press-ganged-navigator.md — Red-cell must not implement + pressed-crew.md — Crew working outside their role + silent-watch.md — Stale context + skeleton-crew.md — Do not spawn one crew for atomic tasks + split-keel.md — Do not share files between agents + storm-surge.md — Poor task decomposition + tidal-pull.md — Memory loss across handoffs + unclassified-engagement.md — Tasks without risk tier classification agents/ — Agent interface definitions demos/ — Example applications built with Nelson scripts/ — Maintenance & utility scripts @@ -84,3 +130,6 @@ Plugin installs are cached snapshots — they do not auto-update. Users must re- ## Environment `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set to enable the `agent-team` execution mode (configured in `.claude/settings.local.json`). + +## This Project Uses Beans to Manage Issues +**IMPORTANT**: before you do anything else, run the `beans prime` command and heed its output. \ No newline at end of file diff --git a/skills/nelson/SKILL.md b/skills/nelson/SKILL.md index 124a70c..fc3c32e 100644 --- a/skills/nelson/SKILL.md +++ b/skills/nelson/SKILL.md @@ -8,6 +8,16 @@ argument-hint: "[mission description]" Execute this workflow for the user's mission. +## Quick Start + +Nelson coordinates agent squadrons using Royal Navy operational doctrine -- sailing orders define the mission, a squadron executes it, and the admiral keeps the quarterdeck. + +**For a simple mission**, just provide your goal. Nelson will handle sailing orders, squadron formation, and execution. A single captain on a frigate can deliver most straightforward tasks without crew. + +**Use the full workflow when** the mission involves parallel work across multiple files, requires risk-tiered quality gates, or benefits from explicit coordination checkpoints. + +For the full workflow, continue reading below. + ## 1. Issue Sailing Orders - Review the user's brief for ambiguity. If the outcome, scope, or constraints are unclear, ask the user to clarify before drafting sailing orders. @@ -17,6 +27,7 @@ Execute this workflow for the user's mission. - Define stop criteria and required handoff artifacts. You MUST read `references/admiralty-templates/sailing-orders.md` and use the sailing-orders template when the user does not provide structure. +You may use `references/sailing-orders-wizard.md` to guide interactive sailing order creation. **Session Hygiene:** Before forming the squadron, execute session hygiene per `references/damage-control/session-hygiene.md`. Clear stale damage reports and turnover briefs from any previous session. Skip this step when resuming an interrupted session. @@ -49,7 +60,9 @@ You MUST consult the Standing Orders table below before forming the squadron. 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 read `references/dynamic-task-ledger.md` for the living battle plan pattern. You MUST consult the Standing Orders table below when assigning files or if scope is unclear. +You may allocate per-ship token budgets using `references/damage-control/bulkhead-doctrine.md`. **Before proceeding to Step 4:** Verify sailing orders exist, squadron is formed, and every task has an owner, deliverable, and action station tier. @@ -73,8 +86,11 @@ You MUST consult the Standing Orders table below when assigning files or if scop You MUST use `references/admiralty-templates/quarterdeck-report.md` for the quarterdeck report template. You MUST use `references/admiralty-templates/damage-report.md` for damage report format. +You MUST run soundings between checkpoints per `references/damage-control/soundings.md`. 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. +You may use `references/dynamic-task-ledger.md` to update the battle plan at each checkpoint. +When the mission cannot deliver full scope, use `references/damage-control/colours-struck.md` for graceful degradation. ## 5. Set Action Stations @@ -92,6 +108,8 @@ You MUST use `references/commendations.md` for recognition signals and graduated 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. +You may use `references/red-cell-challenge-library.md` to seed red-cell reviews with domain-specific failure patterns. +You may call Broadside at integration milestones per `references/broadside-quality-gates.md`. ## 6. Stand Down And Log Action @@ -106,10 +124,11 @@ You MUST consult the Standing Orders table below if tasks lack a tier or red-cel 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. +You may record squadron metrics using `references/squadron-metrics.md`. ## Standing Orders -Consult the specific standing order that matches the situation. +Consult the specific standing order that matches the situation. If unsure which standing order applies, use `references/standing-order-troubleshooter.md`. | Situation | Standing Order | |---|---| @@ -125,6 +144,15 @@ Consult the specific standing order that matches the situation. | 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` | +| Stale context in an agent's working state | `references/standing-orders/silent-watch.md` | +| Multiple agents interpreting the same order differently | `references/standing-orders/crossing-signals.md` | +| Tasks blocking each other in a circular dependency | `references/standing-orders/circular-tides.md` | +| Multiple agents unknowingly doing the same work | `references/standing-orders/ghost-crews.md` | +| Output quality degrading silently over time | `references/standing-orders/fraying-tether.md` | +| Unclear who has decision authority | `references/standing-orders/chain-break.md` | +| Critical context lost during handoffs | `references/standing-orders/tidal-pull.md` | +| Tasks too large, vague, or interdependent | `references/standing-orders/storm-surge.md` | +| Low-priority blocker holding up high-value work | `references/standing-orders/cutting-the-line.md` | ## Damage Control @@ -141,6 +169,19 @@ Consult the specific procedure that matches the situation. | Ship's context window depleted, needs replacement | `references/damage-control/relief-on-station.md` | | Ship context window approaching limits | `references/damage-control/hull-integrity.md` | | Starting a new session with stale data from a previous mission | `references/damage-control/session-hygiene.md` | +| Proactive token budget monitoring between checkpoints | `references/damage-control/soundings.md` | +| Mission needs graceful degradation instead of full abort | `references/damage-control/colours-struck.md` | +| Per-ship token budgets and cascading failure prevention | `references/damage-control/bulkhead-doctrine.md` | + +## Ecosystem + +Optional extensions and tooling. Load on demand. + +| Feature | Reference | +|---|---| +| Automated damage control via Claude Code hooks | `references/event-driven-hooks.md` | +| Companion plugin development and distribution | `references/companion-plugins.md` | +| Squadron performance metrics | `references/squadron-metrics.md` | ## Admiralty Doctrine diff --git a/skills/nelson/references/admiralty-templates/captains-log.md b/skills/nelson/references/admiralty-templates/captains-log.md index 743e8ed..553a38a 100644 --- a/skills/nelson/references/admiralty-templates/captains-log.md +++ b/skills/nelson/references/admiralty-templates/captains-log.md @@ -6,6 +6,22 @@ Mission summary: - achieved outcome: - success metric result: +Plan vs. Reality: +- planned tasks: + - [task as defined in the battle plan] +- actual tasks: + - [task as executed, noting any added/removed/changed tasks] +- key divergences: + - divergence: [where the mission departed from the battle plan] + reason: [why the departure occurred] +- decision points: + - decision: [moment where the admiral chose a different course] + alternatives considered: [what else was on the table] + rationale: [why this course was chosen] +- lessons learned: + - lesson: [what should be done differently next time based on the delta] + recommendation: [concrete change to adopt in future missions] + Delivered artifacts: - artifact: - location: @@ -35,3 +51,12 @@ Reusable patterns: - adopt: - avoid: ``` + +## Plan vs. Reality — Guidance + +The Plan vs. Reality section captures the delta between what the squadron set out to do and what actually happened. It sits immediately after the mission summary so the admiral can assess execution fidelity before reading the detail. + +- **Planned tasks vs. Actual tasks**: List every task from the original battle plan alongside the tasks that were actually executed. Note additions, removals, and material changes to scope or deliverables. +- **Key divergences**: Record each point where execution departed from the plan. State the divergence and the reason — was it a blocker, a discovery during execution, a scope change, or an admiral decision? +- **Decision points**: Capture the moments where the admiral or a captain chose a different course. Include the alternatives that were considered and why the chosen path won. +- **Lessons learned**: Distil the delta into concrete recommendations. What should the squadron do differently on the next mission? Focus on actionable changes, not general observations. diff --git a/skills/nelson/references/admiralty-templates/quarterdeck-report.md b/skills/nelson/references/admiralty-templates/quarterdeck-report.md index 459b4a5..e655512 100644 --- a/skills/nelson/references/admiralty-templates/quarterdeck-report.md +++ b/skills/nelson/references/admiralty-templates/quarterdeck-report.md @@ -1,31 +1,39 @@ # Quarterdeck Report Template +Scannable checkpoint report for the admiral. The entire report should be readable in 30 seconds. + ```text -Checkpoint time: +STATUS: [ON TRACK / AT RISK / BLOCKED] — [X/Y] tasks complete, [N blockers / no blockers] Progress: -- pending: -- in_progress: -- completed: - -Blockers: -- blocker: - owner: - next action: - eta: - -Budget: -- token/time spent: -- token/time remaining: - -Risk updates: -- new/changed risks: -- mitigation: - -Signal flag (if any): -- recognition: - -Admiral decision: -- continue / rescope / stop: -- rationale: +| Ship | Task | Status | % Complete | +|----------------|-----------------------|-------------|------------| +| HMS [name] | [task summary] | [status] | [XX]% | +| HMS [name] | [task summary] | [status] | [XX]% | + +Hull Integrity: +| Ship | Condition | Hull % | Relief? | +|----------------|-----------|--------|---------| +| HMS [name] | [XRAY] | [XX]% | No | +| HMS [name] | [YOKE] | [XX]% | No | + +Blockers: [omit section if none] +- [blocker description] — owner: [name], ETA: [time] + +Budget: [spent] / [remaining] tokens — burn rate [X]% per checkpoint + +Admiral Decision: [continue / rescope / stop] — [brief rationale] + +Signal Flags: [omit section if no recognition warranted] +- [recognition] ``` + +## Usage Notes + +- **STATUS line** is the first thing the admiral reads. State the headline, not the detail. +- **Progress table** replaces the flat list. One row per task, sortable by status. +- **Hull Integrity board** gives material condition at a glance. Refer to `references/damage-control/hull-integrity.md` for condition definitions (XRAY, YOKE, ZEBRA, ZEBRA Critical). +- **Blockers** appear only when they exist. Each blocker fits on a single line with owner and ETA. +- **Budget** is a single line. Burn rate lets the admiral project whether the budget will hold. +- **Admiral Decision** is a single line. The rationale should be one sentence. +- **Signal Flags** appear only when recognition is warranted. Omit the section entirely if there is nothing to report. diff --git a/skills/nelson/references/broadside-quality-gates.md b/skills/nelson/references/broadside-quality-gates.md new file mode 100644 index 0000000..a9273e4 --- /dev/null +++ b/skills/nelson/references/broadside-quality-gates.md @@ -0,0 +1,59 @@ +# Broadside — Synchronised Quality Gates + +A coordinated checkpoint where all ships submit validation evidence simultaneously, enabling cross-ship consistency checks. Loaded on demand. + +## Concept + +Named after a warship firing all guns on one side simultaneously. A Broadside is a coordinated quality gate where ALL ships pause and submit their outputs at the same time. Where individual ship reviews catch single-ship defects, a Broadside catches integration failures — the gaps between ships that no single captain can see. + +## When to Call Broadside + +The admiral signals Broadside in any of the following circumstances: + +- At pre-defined milestones in the battle plan. +- Before final synthesis when multiple ships' outputs must integrate. +- When the admiral suspects cross-ship inconsistencies. +- Recommended for Station 2+ work where integration failures are the primary risk. + +## Broadside Procedure + +1. **Admiral signals "Broadside"** — all ships pause current work immediately. +2. **Each ship submits** three items to the admiral: + - Current deliverable in its present state. + - Validation evidence (tests, checks, or review notes). + - A list of assumptions about other ships' outputs. +3. **Red-cell navigator reviews ALL submissions at once**, specifically checking: + - Cross-ship consistency — do outputs align on shared interfaces, naming, and data formats? + - Integration points — will these pieces fit together without modification? + - Assumption validation — do ships' assumptions about each other hold true? +4. **Red-cell reports findings to the admiral.** +5. **Admiral makes a single go/no-go decision for the entire set.** +6. **Outcome:** + - If go: all ships proceed to the next phase. + - If no-go: admiral identifies which ships need rework and in what order. + +## Broadside Report Format + +``` +Broadside checkpoint: [milestone name] +Ships reporting: [list] +Cross-ship consistency: pass/fail +Integration check: pass/fail +Assumption conflicts: [list or "none"] +Decision: go / rework [ships] +``` + +The red-cell navigator completes this report and delivers it to the admiral. The admiral records the decision in the Captain's Log. + +## Anti-Patterns + +| Anti-pattern | Why it matters | +|---|---| +| Calling Broadside too frequently | Overhead exceeds benefit. Ships lose momentum to repeated pauses. Reserve Broadside for genuine integration milestones. | +| Skipping Broadside for Station 2+ integration work | Integration failures at Station 2+ carry high blast radius. Skipping the checkpoint trades short-term speed for late-stage rework. | +| Individual ships proceeding past the Broadside point | One ship advancing while others wait defeats the purpose. The value is in simultaneous review — partial submissions produce incomplete consistency checks. | + +## Cross-References + +- `action-stations.md` — Station tier definitions that determine when Broadside is recommended. +- `admiralty-templates/red-cell-review.md` — Review template used by the red-cell navigator during Broadside. diff --git a/skills/nelson/references/companion-plugins.md b/skills/nelson/references/companion-plugins.md new file mode 100644 index 0000000..d34b79d --- /dev/null +++ b/skills/nelson/references/companion-plugins.md @@ -0,0 +1,111 @@ +# Companion Plugin Ecosystem + +Nelson core provides the operational framework — sailing orders, squadron composition, quarterdeck rhythm, action stations, and damage control. Companion plugins extend this framework for specific domains, organisations, or workflows without modifying core files. The core stays lean; extensibility lives in the fleet auxiliary. + +## Core Principle + +Nelson follows a ship-and-shore model. The core skill is the ship: self-contained, seaworthy, and opinionated about how missions are run. Companion plugins are the shore establishment: they supply provisions, specialist personnel, and intelligence that the ship draws upon as needed. + +A companion plugin may add references, templates, standing orders, and hook scripts. It must not alter or override core Nelson files. If a companion plugin conflicts with a core instruction, the core instruction prevails. + +## Planned Companion Plugins + +### nelson-templates + +Pre-built battle plans for common mission types. Each template provides a ready-made battle plan structure — sailing orders, squadron composition, crew assignments, and verification criteria — that the admiral can adopt or adapt. + +**Included templates:** + +- **API Development** — Endpoint-per-ship decomposition with contract-first crew roles. +- **Refactoring** — Incremental transformation with red-cell verification at each stage. +- **Documentation** — Parallel authoring with cross-reference consistency checks. +- **Migration** — Phased cutover with rollback checkpoints and compatibility verification. + +### nelson-crew-library + +Organisation-specific crew roles and standing orders. Extends the base crew roles from `crew-roles.md` with domain-specific definitions, custom anti-patterns, and tailored standing orders. + +**Use cases:** + +- Define custom crew roles for specialised domains (e.g., ML Engineer, Data Steward, Security Analyst). +- Add organisation-specific standing orders that reflect internal coding standards or review practices. +- Package domain-specific anti-patterns so captains receive relevant warnings without cluttering the core standing orders. + +### nelson-integrations + +Hooks for external tools that connect Nelson's operational rhythm to existing project management and communication systems. + +**Planned integrations:** + +- **Jira** — Sync battle plan tasks to Jira issues. Update issue status when captains mark tasks complete. +- **GitHub Projects** — Mirror the battle plan as a GitHub Project board. Link ships to project columns. +- **Slack** — Post quarterdeck reports to a designated channel. Surface damage reports and blocker alerts. + +Integration hooks run as companion hook scripts (see `event-driven-hooks.md`) and write to external APIs. They do not alter Nelson's internal coordination model. + +### nelson-metrics + +Dashboard generation from captain's logs. Aggregates the squadron metrics defined in `squadron-metrics.md` across multiple missions to build a longitudinal performance picture. + +**Capabilities:** + +- Parse captain's log entries and extract metric values. +- Generate per-mission and cross-mission summary reports. +- Identify trends in coal consumption, homecoming rate, and seaworthiness index over time. +- Output reports as markdown files suitable for inclusion in project documentation. + +## Plugin Structure + +Each companion plugin follows the standard Claude Code plugin manifest structure. A minimal companion plugin contains: + +``` +nelson-templates/ + .claude-plugin/ + plugin.json — Plugin manifest (name, version, description) + marketplace.json — Marketplace listing (if published) + skills/nelson-templates/ + SKILL.md — Entrypoint describing the plugin's purpose + references/ — Additional reference documents + templates/ — Battle plan templates or other assets +``` + +**Rules for companion plugins:** + +1. The plugin manifest must declare Nelson core as a dependency. +2. All files live under the companion plugin's own namespace. No files are placed in Nelson core's directory tree. +3. References added by a companion plugin are loaded on demand, the same as core references. +4. Companion plugins may add hook scripts under their own `.claude/nelson/hooks/` namespace. +5. Standing orders added by a companion plugin must not contradict core standing orders. + +## Installation + +Companion plugins install via the Claude Code plugin marketplace, the same as Nelson core. + +``` +/plugin install nelson-templates +/plugin install nelson-crew-library +/plugin install nelson-integrations +/plugin install nelson-metrics +``` + +To install from a specific repository before marketplace publication: + +``` +/plugin install /nelson-templates +``` + +## Development Guide + +To create a new companion plugin: + +1. **Scaffold the directory structure** following the layout above. Use the companion plugin's name as the top-level directory. +2. **Write the plugin manifest** in `.claude-plugin/plugin.json`. Include `name`, `version`, `description`, and a `dependencies` field listing `nelson` as a required plugin. +3. **Write the SKILL.md entrypoint.** Describe what the plugin provides and how it extends Nelson core. Reference any new documents in the `references/` directory. +4. **Add references and templates.** Follow the same conventions as Nelson core: H1 title, intro paragraph, H2 sections, Royal Navy tone. +5. **Test locally.** Symlink the plugin into your `.claude/skills/` directory and verify that Nelson can load its references on demand. +6. **Publish.** Create a GitHub repository, add a `marketplace.json`, and register with the Claude Code plugin marketplace. + +## Cross-References + +- `event-driven-hooks.md` — Hook system that companion plugins can extend with additional hook scripts. +- `squadron-metrics.md` — Metric definitions that nelson-metrics aggregates across missions. diff --git a/skills/nelson/references/damage-control/bulkhead-doctrine.md b/skills/nelson/references/damage-control/bulkhead-doctrine.md new file mode 100644 index 0000000..7b96639 --- /dev/null +++ b/skills/nelson/references/damage-control/bulkhead-doctrine.md @@ -0,0 +1,66 @@ +# Bulkhead Doctrine: Cascading Failure Containment + +Use to allocate and enforce per-ship token budgets that prevent a single ship's overconsumption from sinking the squadron. + +Watertight bulkheads on a warship contain flooding to one compartment. The bulkhead doctrine applies the same principle to token budgets: each ship operates within a sealed allocation so that one ship's overrun cannot drain resources from the rest of the fleet. + +## Token Budget Allocation + +The admiral assigns each ship an explicit token allocation during the battle plan, expressed as a percentage of the total mission budget. Allocation is based on task complexity. + +| Task Complexity | Suggested Allocation | +|---|---| +| Simple | 10 -- 15% | +| Medium | 15 -- 25% | +| Complex | 25 -- 35% | + +The sum of all ship allocations plus the admiral reserve must equal 100% of the mission budget. If it does not, adjust allocations or reduce squadron size before issuing sailing orders. + +## Admiral Reserve Pool + +The admiral holds 15 -- 20% of the total budget as a reserve pool. This reserve is not assigned to any ship and is drawn upon only for: + +1. Relief on station operations (spawning replacement ships). +2. Emergency coordination during escalations. +3. Unexpected work discovered mid-mission. +4. Absorbing minor overruns that do not warrant corrective action. + +The reserve is not a general overflow buffer. If the reserve drops below 5%, the admiral must trigger colours struck or scuttle and re-form. + +## Budget Monitoring + +Track actual versus allocated spend at every quarterdeck checkpoint. + +1. Each captain reports current token usage in their damage report. +2. Admiral compares each ship's usage against its allocation. +3. Admiral flags any ship that has consumed 80% or more of its allocation as "bulkhead pressure" on the squadron readiness board. +4. Admiral records budget status in the quarterdeck report under the budget section. + +## Compartment Breach Rules + +A compartment breach occurs when a ship's token consumption threatens the integrity of the wider squadron. The admiral responds according to the severity of the breach. + +| Condition | Classification | Action | +|---|---|---| +| Single ship exceeds its allocation | Contained breach | Admiral triggers crew overrun procedure for that ship. Captain descopes, resolves blockers, or requests relief. | +| Single ship exceeds allocation and reserve is below 10% | Serious breach | Admiral halts the ship immediately and executes relief on station. No further reserve draw permitted for that task. | +| 3+ ships reach ZEBRA hull integrity simultaneously | Catastrophic breach | Admiral pauses ALL new work across the squadron and escalates to Admiralty (human). No work resumes until the Admiralty provides direction. | +| Upstream dependency is at ZEBRA integrity | Blocked compartment | Downstream tasks do not proceed. Admiral reassigns downstream ships to other work or stands them down to conserve budget. | + +## Allocation Procedure + +1. During the battle plan, admiral estimates task complexity for each ship's assignment. +2. Admiral assigns a token allocation percentage to each ship using the suggested ranges above. +3. Admiral verifies that all allocations plus the reserve sum to 100%. +4. Admiral records allocations in the battle plan alongside task assignments. +5. At each quarterdeck checkpoint, admiral reviews actual spend against allocations and adjusts if needed. +6. If a ship completes its task under budget, the surplus returns to the admiral reserve pool. +7. If a ship needs more budget, the admiral may transfer from the reserve pool, but only if the reserve remains above 5% after the transfer. + +## Relationship to Other Damage Control Procedures + +- **Hull Integrity** (`hull-integrity.md`): Threshold definitions that determine when a ship's context consumption is reaching dangerous levels. Bulkhead doctrine adds per-ship budget caps on top of hull integrity monitoring. +- **Crew Overrun** (`crew-overrun.md`): The first response to a contained breach. The captain attempts to recover the ship within its allocation before the admiral intervenes. +- **Colours Struck** (`colours-struck.md`): When multiple compartment breaches occur or the reserve pool is critically low, the admiral may need to degrade mission scope rather than continue at full capacity. +- **Relief on Station** (`relief-on-station.md`): Spawning a replacement ship draws from the admiral reserve. The bulkhead doctrine ensures this draw is tracked and bounded. +- **Scuttle and Re-Form** (`scuttle-and-reform.md`): A catastrophic breach with no viable recovery path leads to full mission abort. diff --git a/skills/nelson/references/damage-control/colours-struck.md b/skills/nelson/references/damage-control/colours-struck.md new file mode 100644 index 0000000..ec02ec0 --- /dev/null +++ b/skills/nelson/references/damage-control/colours-struck.md @@ -0,0 +1,69 @@ +# Colours Struck: Graceful Degradation + +Use when a mission cannot deliver its full scope but can still achieve a meaningful outcome by shedding non-essential work. + +Striking the colours is a controlled withdrawal, not a surrender. The admiral preserves mission-critical deliverables by deliberately deferring lower-priority tasks before budget exhaustion forces an uncontrolled abort. + +## Task Tiers + +At each quarterdeck checkpoint, the admiral classifies every remaining task into one of three tiers. + +| Tier | Label | Definition | +|---|---|---| +| 1 | Mission Critical (MVP) | Must deliver for the mission to be considered successful. Without these, the mission has failed. | +| 2 | High Value | Adds significant value but the mission can succeed without it. Deferral is acceptable if budget demands it. | +| 3 | Polish | Quality-of-life improvements, minor enhancements, or cosmetic work. Can be deferred entirely with no impact on mission success. | + +Tier classification is set during the battle plan and revisited at each quarterdeck checkpoint. Tasks may be re-tiered as the mission evolves. + +## Degradation Levels + +The admiral selects a degradation level based on remaining budget and squadron health. + +| Level | What Proceeds | What Is Deferred | When to Use | +|---|---|---|---| +| Staged Degradation | All Mission Critical tasks plus admiral-selected High Value tasks | Remaining High Value tasks and all Polish tasks | Budget is constrained but not critical. Some high-value work can still be absorbed. | +| Full Degradation | Mission Critical tasks only | All High Value and Polish tasks | Budget is severely constrained. Only MVP deliverables proceed. | +| Abort | Nothing | Everything | Mission cannot succeed even with full degradation. Execute scuttle and re-form. | + +## Trigger Conditions + +Strike the colours when any of the following are true: + +1. Token budget is below 40% with significant work remaining. +2. Time budget is below 30% with significant work remaining. +3. Three or more ships are at ZEBRA hull integrity simultaneously. +4. Admiral judges that full scope delivery is no longer achievable at the current burn rate. + +## Degradation Procedure + +1. Admiral halts new task assignments across the squadron. +2. Admiral classifies all remaining tasks into the three tiers (Mission Critical, High Value, Polish). +3. Admiral selects the appropriate degradation level based on remaining budget and squadron health. +4. Admiral identifies ships assigned to deferred tasks and issues stand-down orders to those ships. +5. Admiral reassigns any freed capacity to Mission Critical tasks that need reinforcement. +6. Admiral updates the battle plan to reflect the reduced scope and records the degradation decision in the quarterdeck report. +7. Ships working on Mission Critical tasks continue without interruption. +8. Admiral produces a Degraded Capability Report (see below). + +## Degraded Capability Report + +The admiral writes a Degraded Capability Report to file at `.claude/nelson/degraded-capability-report.md` and presents it to the Admiralty (human) at stand-down. + +The report contains: + +| Section | Contents | +|---|---| +| Degradation Level | Staged or Full. | +| Trigger | What condition triggered the degradation. | +| Delivered | List of completed tasks with outputs. | +| In Progress | List of Mission Critical tasks still underway. | +| Deferred | List of deferred tasks, their tier, and the reason for deferral. | +| Recommendation | Whether deferred work should be attempted in a follow-up mission, descoped permanently, or abandoned. | + +## Relationship to Other Damage Control Procedures + +- **Scuttle and Re-Form** (`scuttle-and-reform.md`): Use when degradation is insufficient and the mission must be fully aborted. Colours struck is the step before scuttle — always attempt degradation first. +- **Hull Integrity** (`hull-integrity.md`): Threshold definitions that feed the trigger conditions. Three or more ships at ZEBRA triggers colours struck; individual ships at Red or Critical trigger relief on station. +- **Relief on Station** (`relief-on-station.md`): Relief replaces an individual exhausted ship. Colours struck reduces mission scope across the entire squadron. Both may be active simultaneously. +- **Crew Overrun** (`crew-overrun.md`): A crew overrun on multiple ships may be an early signal that degradation is needed. If corrective action fails to recover budget, escalate to colours struck. diff --git a/skills/nelson/references/damage-control/hull-integrity.md b/skills/nelson/references/damage-control/hull-integrity.md index a14c7a5..aa3a96a 100644 --- a/skills/nelson/references/damage-control/hull-integrity.md +++ b/skills/nelson/references/damage-control/hull-integrity.md @@ -2,24 +2,33 @@ Use to monitor and manage context window consumption across the squadron. -## Hull Integrity Thresholds +## Material Conditions -Each ship maintains a hull integrity percentage representing its remaining context window capacity. +Each ship maintains a hull integrity percentage representing its remaining context window capacity. Hull integrity is expressed using Royal Navy material conditions that govern watertight closure throughout the ship. -| Status | Remaining | Action | +| Condition | Remaining | Closure Rules | |---|---|---| -| Green | 75 -- 100% | No action required. Continue normal operations. | -| Amber | 60 -- 74% | Admiral notes the ship on the readiness board. Captain prioritises completing current task and avoids taking new work that would extend the session. | -| Red | 40 -- 59% | Captain files a damage report with `relief_requested: true`. Admiral plans relief on station: spawn a replacement ship, brief it with completed and remaining work, then transfer the task. Captain focuses on producing a clean handoff summary before context runs out. | -| Critical | Below 40% | Admiral executes relief on station immediately. If no replacement is available, admiral descopes the ship's remaining work or redistributes it to ships with Green or Amber status. Captain ceases non-essential activity and writes a final status report. | +| Condition XRAY | 75 -- 100% | Routine cruising. All compartments open, normal operations. No action required. | +| Condition YOKE | 60 -- 74% | Heightened readiness. Non-essential compartments secured. Admiral notes the ship on the readiness board. Captain prioritises completing current task and avoids taking new work that would extend the session. | +| Condition ZEBRA | 40 -- 59% | Action stations. Maximum watertight integrity. Captain files a damage report with `relief_requested: true`. Admiral plans relief on station: spawn a replacement ship, brief it with completed and remaining work, then transfer the task. Captain focuses on producing a clean handoff summary before context runs out. | +| Condition ZEBRA (Critical) | Below 40% | Hull breach imminent. All hands to damage control. Admiral executes relief on station immediately. If no replacement is available, admiral descopes the ship's remaining work or redistributes it to ships at Condition XRAY or YOKE. Captain ceases non-essential activity and writes a final status report. | + +### Interpreting the Conditions + +- **XRAY** reflects peacetime steaming. The ship has ample capacity and operates without restriction. +- **YOKE** is set when the ship enters waters that demand caution. Context is being consumed at a rate that warrants attention, but the ship can still complete its current task. +- **ZEBRA** means the ship is closed up for action. Context is scarce and every token must count. The ship's priority shifts from task completion to producing a clean handoff. +- **ZEBRA (Critical)** is ZEBRA with active flooding. The ship is in danger of losing useful output capacity entirely. Immediate relief or descoping is mandatory. + +Transition between conditions is one-directional during a session: a ship moves from XRAY toward ZEBRA as context is consumed. A ship never returns to a lower condition without relief on station (a fresh ship starts at Condition XRAY). ## Squadron Readiness Board The admiral maintains a readiness board to track hull integrity across all ships. Build the board by reading damage reports from `.claude/nelson/damage-reports/`. 1. At each quarterdeck checkpoint, collect the latest damage report from every active ship. -2. List each ship with its hull integrity status, percentage, and whether relief is requested. -3. Flag any ship at Red or Critical for immediate attention. +2. List each ship with its material condition, hull integrity percentage, and whether relief is requested. +3. Flag any ship at Condition ZEBRA or ZEBRA (Critical) for immediate attention. 4. Record the board in the quarterdeck report under the budget section. The readiness board gives the admiral a single view of squadron endurance and drives decisions about task reassignment, descoping, and relief. @@ -30,14 +39,14 @@ Check hull integrity at every quarterdeck checkpoint: 1. Each captain files a damage report using the template from `references/admiralty-templates/damage-report.md`. 2. Admiral reads all damage reports and updates the squadron readiness board. -3. If any ship has crossed a threshold boundary since the last checkpoint, admiral takes the action defined for that threshold. +3. If any ship has crossed a condition boundary since the last checkpoint, admiral takes the action defined for that condition. 4. Admiral records hull integrity status in the quarterdeck report. -Between checkpoints, captains file an immediate damage report when hull integrity crosses any threshold boundary. Do not wait for the next scheduled checkpoint to report a status change. +Between checkpoints, captains file an immediate damage report when hull integrity crosses any condition boundary. Do not wait for the next scheduled checkpoint to report a change in material condition. ## Relief on Station -Trigger relief on station when a ship reaches Red hull integrity. Execute as follows: +Trigger relief on station when a ship reaches Condition ZEBRA. Execute as follows: 1. Admiral spawns a replacement ship with the same role and ship class. 2. The outgoing captain writes a handoff summary: task definition, completed sub-tasks, partial outputs, known blockers, and file ownership. @@ -46,22 +55,23 @@ Trigger relief on station when a ship reaches Red hull integrity. Execute as fol 5. Admiral updates the battle plan to reflect the new ship assignment. 6. Admiral issues a shutdown request to the outgoing ship. -If multiple ships reach Red simultaneously, prioritise relief for the ship closest to Critical. +If multiple ships reach Condition ZEBRA simultaneously, prioritise relief for the ship closest to ZEBRA (Critical). ## Flagship Self-Monitoring The admiral must monitor its own hull integrity with the same discipline applied to the squadron. 1. Admiral tracks its own token usage and calculates hull integrity at each checkpoint. -2. At Amber, admiral begins preparing a session resumption handoff using `references/damage-control/session-resumption.md`. -3. At Red, admiral writes a full quarterdeck report and session state to disk, then signals the Admiralty (human) that a session resumption will be needed. -4. The admiral does not wait for Critical. An admiral at Critical risks losing coordination state that cannot be recovered. +2. At Condition YOKE, admiral begins preparing a session resumption handoff using `references/damage-control/session-resumption.md`. +3. At Condition ZEBRA, admiral writes a full quarterdeck report and session state to disk, then signals the Admiralty (human) that a session resumption will be needed. +4. The admiral does not wait for ZEBRA (Critical). An admiral at ZEBRA (Critical) risks losing coordination state that cannot be recovered. ## Relationship to Other Damage Control Procedures Hull integrity monitoring works alongside existing damage control procedures: -- **Session Resumption** (`session-resumption.md`): Use when hull integrity reaches Critical and the session must end. The session resumption procedure picks up from the last quarterdeck report. -- **Crew Overrun** (`crew-overrun.md`): A crew overrun accelerates hull integrity loss. When a captain detects a crew overrun, the corrective action should account for the ship's current hull integrity — a ship already at Amber has less margin to absorb an overrun than one at Green. -- **Man Overboard** (`man-overboard.md`): Replacing a stuck agent consumes additional context. Factor hull integrity into the decision to replace versus descope. -- **Scuttle and Reform** (`scuttle-and-reform.md`): When the flagship reaches Red and multiple ships are also at Red or Critical, consider scuttling the current mission and reforming with fresh context rather than attempting piecemeal relief. +- **Session Resumption** (`session-resumption.md`): Use when hull integrity reaches ZEBRA (Critical) and the session must end. The session resumption procedure picks up from the last quarterdeck report. +- **Crew Overrun** (`crew-overrun.md`): A crew overrun accelerates hull integrity loss. When a captain detects a crew overrun, the corrective action should account for the ship's current material condition — a ship already at Condition YOKE has less margin to absorb an overrun than one at Condition XRAY. +- **Man Overboard** (`man-overboard.md`): Replacing a stuck agent consumes additional context. Factor the ship's material condition into the decision to replace versus descope. +- **Scuttle and Reform** (`scuttle-and-reform.md`): When the flagship reaches Condition ZEBRA and multiple ships are also at ZEBRA or ZEBRA (Critical), consider scuttling the current mission and reforming with fresh context rather than attempting piecemeal relief. +- **Soundings** (`soundings.md`): Proactive budget monitoring between quarterdeck checkpoints. Soundings detect approaching condition boundaries early so the admiral can act before a ship crosses into ZEBRA unexpectedly. diff --git a/skills/nelson/references/damage-control/soundings.md b/skills/nelson/references/damage-control/soundings.md new file mode 100644 index 0000000..dc01dfd --- /dev/null +++ b/skills/nelson/references/damage-control/soundings.md @@ -0,0 +1,83 @@ +# Soundings: Proactive Budget Cliff Detection + +Use to detect approaching context window exhaustion before a ship crosses into a critical material condition. Soundings are the navigational practice of measuring water depth to avoid running aground — applied here to token budgets to avoid running aground on a context cliff. + +## Purpose + +Quarterdeck checkpoints catch condition changes after they happen. Soundings detect them before they happen. A ship that knows it will reach Condition ZEBRA in two turns can prepare an orderly handoff. A ship that discovers it is already at ZEBRA (Critical) cannot. + +## When to Take Soundings + +Take soundings every 5 to 10 turns, independent of the quarterdeck rhythm. Soundings are lightweight and should not wait for a full checkpoint cycle. + +- Every captain takes soundings of their own ship's budget. +- The admiral takes soundings of the flagship budget and reviews ship-level soundings at each quarterdeck checkpoint. +- Between checkpoints, captains report soundings to the admiral only when the forecast is alarming (see Escalation below). + +## Sounding Procedure + +1. **Read current hull integrity.** Determine the ship's remaining context window as a percentage. +2. **Calculate burn rate.** Divide the tokens consumed over the last N turns by N (where N is typically 5 turns, or fewer if the ship has completed fewer than 5 turns). Express as tokens per turn. +3. **Estimate turns to ZEBRA (Critical).** Calculate the number of turns until hull integrity falls below 40%: + + ``` + tokens_to_critical = remaining_tokens - (total_capacity * 0.40) + turns_to_critical = tokens_to_critical / burn_rate + ``` + +4. **Estimate turns to Condition ZEBRA.** Calculate the number of turns until hull integrity falls below 60%: + + ``` + tokens_to_zebra = remaining_tokens - (total_capacity * 0.60) + turns_to_zebra = tokens_to_zebra / burn_rate + ``` + +5. **Compare against thresholds.** If turns to ZEBRA (Critical) is less than 3, escalate immediately. + +## Soundings Report + +File a soundings report using the following format. This is a lightweight status — not a full damage report. + +``` +Ship: {ship-name} +Material Condition: {XRAY | YOKE | ZEBRA | ZEBRA (Critical)} +Hull Integrity: {percentage}% +Burn Rate: {tokens-per-turn} tokens/turn (measured over last {N} turns) +Turns to ZEBRA: {estimate} +Turns to ZEBRA (Critical): {estimate} +Forecast: {STEADY | CLOSING | SHOAL WATER} +``` + +### Forecast Definitions + +- **STEADY**: Turns to ZEBRA (Critical) is 10 or more. No concern. +- **CLOSING**: Turns to ZEBRA (Critical) is between 3 and 9. Monitor closely; increase sounding frequency to every 3 turns. +- **SHOAL WATER**: Turns to ZEBRA (Critical) is fewer than 3. Immediate escalation required. + +## Escalation + +When a sounding returns SHOAL WATER: + +1. Captain sends the soundings report to the admiral immediately. Do not wait for the next quarterdeck checkpoint. +2. Admiral assesses whether the ship can complete its current task within the remaining budget. +3. If the task cannot complete, admiral initiates relief on station per `hull-integrity.md` and `relief-on-station.md`. +4. If the task is close to completion, admiral may authorise the captain to push through — but only if the estimated remaining work is fewer turns than turns to ZEBRA (Critical). + +When a sounding returns CLOSING: + +1. Captain notes the forecast in their next damage report. +2. Captain increases sounding frequency to every 3 turns. +3. Admiral factors the ship's trajectory into readiness board decisions at the next quarterdeck checkpoint. + +## Flagship Soundings + +The admiral takes soundings of the flagship budget at the same cadence as ship captains. Flagship SHOAL WATER is the highest-priority escalation in the squadron because losing the admiral's coordination context is unrecoverable within the current session. + +1. At CLOSING, admiral begins writing session state to disk incrementally. +2. At SHOAL WATER, admiral writes a full quarterdeck report and flagship turnover brief, then signals the Admiralty (human) that a session resumption will be needed. + +## Relationship to Hull Integrity + +Soundings do not replace hull integrity monitoring — they augment it. Hull integrity thresholds define the material conditions and the actions required at each condition. Soundings provide early warning so those actions can be planned rather than reactive. + +See `hull-integrity.md` for material condition definitions and threshold percentages. diff --git a/skills/nelson/references/dynamic-task-ledger.md b/skills/nelson/references/dynamic-task-ledger.md new file mode 100644 index 0000000..52f52d1 --- /dev/null +++ b/skills/nelson/references/dynamic-task-ledger.md @@ -0,0 +1,70 @@ +# Dynamic Task Ledger + +The battle plan is a living document. It evolves with mission reality rather than remaining fixed at the point of first contact. At each quarterdeck checkpoint, the admiral reviews the ledger and updates task priorities, the dependency graph, ship assignments, and scope. This pattern is inspired by the continuously re-evaluated task ledger in Microsoft's Magentic-One framework. + +## Concept + +A static battle plan assumes perfect information at planning time. In practice, new information surfaces as ships report progress, blockers appear, and priorities shift. The dynamic task ledger treats the battle plan as the current best understanding of the mission, not a contract. The admiral owns the ledger and is responsible for keeping it accurate. + +The ledger serves two purposes: + +1. **Situational awareness** — any agent can read the ledger to understand current priorities, dependencies, and assignments. +2. **Decision record** — changes to the ledger are communicated at checkpoints, creating an audit trail of how and why the plan evolved. + +## Ledger Format + +Maintain a compact, scannable table as the authoritative state of all active tasks. + +```text +| Task ID | Ship | Status | Priority | Dependencies | Notes | +|---------|----------------|-------------|----------|--------------|------------------------------| +| T1 | HMS Argyll | Complete | — | — | Merged to main | +| T2 | HMS Kent | In progress | High | — | On track, 60% complete | +| T3 | HMS Lancaster | In progress | Medium | T2 | Blocked until T2 delivers API| +| T4 | Unassigned | Pending | Low | T2, T3 | Descope candidate | +``` + +- **Task ID**: Short identifier matching the battle plan. +- **Ship**: Assigned ship or "Unassigned" if not yet allocated. +- **Status**: Pending, In progress, Blocked, Complete, or Descoped. +- **Priority**: High, Medium, or Low. Relative to other active tasks. +- **Dependencies**: Task IDs that must complete before this task can proceed. +- **Notes**: One-line summary of current state, blockers, or decisions. + +## Ledger Update Procedure + +At each quarterdeck checkpoint, the admiral walks through these steps in order. + +1. **Review completed tasks.** Remove them from the active list. Confirm deliverables are verified and accepted. +2. **Reassess priorities.** New information may change the relative value of remaining tasks. Re-rank High, Medium, and Low accordingly. +3. **Update the dependency graph.** Remove resolved dependencies. Add newly discovered dependencies. Flag any circular dependencies as immediate blockers. +4. **Reallocate resources.** Ships that have completed their tasks carry spare capacity. Assign them to the highest-priority unblocked work or stand them down. +5. **Flag drift.** If any active task has diverged from the original sailing orders metric, mark it for re-scoping or descoping. +6. **Communicate changes.** Signal affected captains with their updated orders. Every priority change, reassignment, or scope adjustment must reach the relevant captain before the next work period begins. + +## When to Reprioritise + +Reprioritisation happens at quarterdeck checkpoints, not continuously. The admiral should update the ledger when any of the following conditions are met. + +| Trigger | Action | +|---|---| +| New information changes relative value of tasks | Re-rank affected tasks | +| A blocker shifts the critical path | Reorder dependencies and reassign if needed | +| A ship completes early and has capacity | Assign highest-priority unblocked task | +| Budget constraints require descoping | Mark lowest-priority tasks as Descoped | +| A task has drifted from the original metric | Re-scope or descope; reference sailing orders | + +## Anti-Patterns + +| Anti-Pattern | Problem | Remedy | +|---|---|---| +| Static battle plan that never updates | Plan diverges from reality; ships work on stale priorities | Update the ledger at every quarterdeck checkpoint. See `standing-orders/drifting-anchorage.md` | +| Updating without communicating | Captains continue on outdated orders; wasted effort | Every ledger change must be signalled to affected captains before the next work period | +| Reprioritising every turn | Constant churn prevents ships from making progress; thrashing | Restrict updates to quarterdeck checkpoints only, not mid-period | +| Admiral hoarding the ledger | Captains cannot self-organise or anticipate upcoming work | Keep the ledger visible to all squadron agents | + +## Cross-References + +- `admiralty-templates/battle-plan.md` — the initial battle plan template that seeds the ledger. +- `admiralty-templates/quarterdeck-report.md` — the checkpoint report where ledger updates are communicated. +- `standing-orders/drifting-anchorage.md` — the standing order governing scope drift, which the ledger helps detect and correct. diff --git a/skills/nelson/references/event-driven-hooks.md b/skills/nelson/references/event-driven-hooks.md new file mode 100644 index 0000000..0023cbc --- /dev/null +++ b/skills/nelson/references/event-driven-hooks.md @@ -0,0 +1,122 @@ +# Event-Driven Hooks for Automated Damage Control + +Claude Code supports hooks — shell commands triggered on specific events during a session. Nelson leverages these hooks to automate routine monitoring and damage control tasks that would otherwise require manual admiral attention, reducing cognitive load at the quarterdeck. + +## Hook Types Available + +Claude Code exposes three hook events that Nelson can act upon: + +| Hook | Fires When | Nelson Use Case | +|---|---|---| +| **PreToolUse** | Before a tool runs | Gate dangerous operations, enforce standing orders | +| **PostToolUse** | After a tool completes | Monitor token burn, detect idle crew, inject checkpoint reminders | +| **Stop** | When an agent session ends | Persist session state, auto-save captain's log | + +Hooks execute shell commands. They can read environment variables, write files, and trigger alerts, but they cannot issue Claude prompts or make coordination decisions. The admiral retains all decision-making authority. + +## Recommended Hooks + +### Token Burn Monitor + +**Event:** PostToolUse + +After each tool use, check cumulative token usage against hull integrity thresholds. When a ship crosses a material condition boundary (XRAY to YOKE, YOKE to ZEBRA, or into ZEBRA Critical), the hook auto-files a damage report to `.claude/nelson/damage-reports/`. + +This removes the burden of manual hull integrity tracking from captains and ensures the admiral's readiness board stays current between quarterdeck checkpoints. + +**Behaviour:** + +1. Read current token usage from the session environment. +2. Calculate hull integrity percentage. +3. Compare against the last recorded material condition. +4. If a boundary has been crossed, write a damage report using the template from `admiralty-templates/damage-report.md`. +5. If the new condition is ZEBRA or ZEBRA (Critical), write an additional alert file that the admiral's next checkpoint will surface. + +### Idle Crew Detection + +**Event:** PostToolUse + +Alert when a crew member has produced no file changes in a configurable number of turns (default: 5). Prolonged inactivity may indicate confusion, a blocked state, or unclear orders — all conditions that benefit from early intervention rather than discovery at the next quarterdeck checkpoint. + +**Behaviour:** + +1. After each tool use, record the agent identifier and whether any file modifications occurred. +2. Maintain a rolling count of consecutive turns with no file changes per agent. +3. When the threshold is exceeded, write an alert to `.claude/nelson/alerts/` naming the idle agent and the turn count. +4. The admiral reviews alerts at the next checkpoint and decides whether to signal, reassign, or unblock. + +### Forced Checkpoint Prompt + +**Event:** PostToolUse + +After every N tool uses (recommended default: 20), inject a reminder to run a quarterdeck checkpoint. This acts as a dead-reckoning fix — preventing the admiral from becoming absorbed in implementation and drifting past scheduled coordination points. + +**Behaviour:** + +1. Increment a per-session tool use counter after each PostToolUse event. +2. When the counter reaches the configured interval, write a checkpoint reminder file to `.claude/nelson/alerts/`. +3. Reset the counter. +4. The reminder does not force a checkpoint. It surfaces the prompt; the admiral decides whether to act on it or defer. + +### Auto-Save Captain's Log + +**Event:** Stop + +When a session ends — whether by completion, context exhaustion, or manual termination — automatically persist the current session state to disk. This ensures that even an unexpected session end produces a recoverable record. + +**Behaviour:** + +1. On the Stop event, gather available session state: battle plan status, filed damage reports, unresolved blockers, and the last quarterdeck report. +2. Write a structured log entry to `.claude/nelson/captains-log/` with a timestamp and session identifier. +3. If a turnover brief has already been written, note its location in the log entry. If not, write a minimal state snapshot sufficient for session resumption. + +## Configuration + +Hooks are configured in the Claude Code settings file (`.claude/settings.json` or `.claude/settings.local.json`) under the `hooks` key. Each hook specifies the event, an optional tool name matcher, and the shell command to execute. + +Example configuration: + +```json +{ + "hooks": { + "PostToolUse": [ + { + "command": "bash .claude/nelson/hooks/token-burn-monitor.sh", + "description": "Auto-file damage report on hull integrity threshold crossing" + }, + { + "command": "bash .claude/nelson/hooks/idle-crew-detection.sh", + "description": "Alert on crew inactivity exceeding threshold" + }, + { + "command": "bash .claude/nelson/hooks/checkpoint-prompt.sh", + "description": "Inject quarterdeck checkpoint reminder every 20 tool uses" + } + ], + "Stop": [ + { + "command": "bash .claude/nelson/hooks/auto-save-log.sh", + "description": "Persist captain's log and session state on session end" + } + ] + } +} +``` + +Hook scripts live in `.claude/nelson/hooks/`. Each script is a standalone shell script with no runtime dependencies beyond standard Unix utilities. + +## Limitations + +Hooks are automation, not intelligence. They observe and record but do not coordinate. + +- Hooks run shell commands, not Claude prompts. They cannot reason about context or make judgement calls. +- Hooks cannot send messages to other agents. They write files that agents read at their next opportunity. +- Hook failures are silent by default. A failing hook does not halt the session, but it may leave gaps in monitoring. +- The admiral still makes all coordination decisions: relief on station, task reassignment, descoping, and escalation are human-in-the-loop or admiral-in-the-loop actions. +- Hook configuration is per-installation. Each user must configure hooks in their own settings file. + +## Cross-References + +- `damage-control/hull-integrity.md` — Material condition thresholds and the squadron readiness board. +- `damage-control/soundings.md` — Proactive budget monitoring between quarterdeck checkpoints. +- `admiralty-templates/damage-report.md` — Template used by the token burn monitor hook. diff --git a/skills/nelson/references/red-cell-challenge-library.md b/skills/nelson/references/red-cell-challenge-library.md new file mode 100644 index 0000000..8b39687 --- /dev/null +++ b/skills/nelson/references/red-cell-challenge-library.md @@ -0,0 +1,60 @@ +# Red-Cell Challenge Library + +Seed red-cell reviews with domain-specific failure patterns instead of requiring the red-cell navigator to invent challenges from scratch. Loaded on demand. + +## Purpose + +The red-cell navigator currently generates challenges ad hoc. A library of known failure patterns by domain accelerates reviews and ensures coverage of common risks. Select the categories relevant to the task under review and use the patterns as a checklist. + +## Auth and Security + +| Pattern | What to look for | +|---|---| +| Token expiry edge cases | Refresh token behaviour during long-running operations; silent failures when tokens expire mid-request. | +| Privilege escalation | Role manipulation that grants unintended access; parameter tampering on role or permission fields. | +| Injection vectors | SQL, command, and template injection in user-supplied inputs; inadequate parameterisation or escaping. | +| Session fixation and replay | Session tokens that survive authentication state changes; replay of captured tokens after logout. | +| CORS misconfiguration | Overly permissive origins; credentials flag combined with wildcard origins; missing preflight validation. | + +## Data Integrity + +| Pattern | What to look for | +|---|---| +| Race conditions in concurrent writes | Two writers modifying the same record without locking or optimistic concurrency control. | +| Partial writes leaving inconsistent state | Operations that update multiple records without transactional guarantees; incomplete rollback on failure. | +| Schema drift between services | Producer and consumer disagreeing on field types, required fields, or enum values after independent deployments. | +| Orphaned records from failed cascading deletes | Parent record removed but child records persist because the cascade failed or was never configured. | +| Timezone and encoding edge cases | Implicit timezone conversions; mixed UTC and local time comparisons; non-UTF-8 input causing silent corruption. | + +## API Design + +| Pattern | What to look for | +|---|---| +| Breaking changes to public contracts | Renamed or removed fields, changed response shapes, or altered status codes without versioning. | +| Pagination edge cases | Empty pages, last-page boundary, concurrent modification between page fetches, off-by-one on page indices. | +| Rate limit behaviour under burst traffic | Missing or misconfigured rate limits; unclear client feedback when limits are hit; retry storms. | +| Error response format inconsistencies | Mixed error shapes across endpoints; missing error codes or messages; stack traces leaking in production. | +| Versioning strategy gaps | No deprecation path for old versions; multiple active versions with divergent behaviour; header vs. path confusion. | + +## Infrastructure + +| Pattern | What to look for | +|---|---| +| DNS propagation delays | Deployments that assume instant DNS updates; TTL misconfiguration causing stale resolution. | +| Certificate expiry and rotation | Missing automated renewal; hard-coded certificate paths; services that fail silently on expired certificates. | +| Connection pool exhaustion | Pool limits too low for peak load; connections leaked by error paths; no monitoring on pool utilisation. | +| Cold start latency in serverless | User-facing latency spikes after idle periods; timeout configurations that do not account for cold starts. | +| Disk space exhaustion from logging | Unbounded log growth; missing log rotation; verbose debug logging left enabled in production. | + +## Usage + +The red-cell navigator selects relevant categories for the task under review and uses the patterns as a checklist. Not all patterns apply to every review — select based on the task domain. When reviewing a task that spans multiple categories, combine the relevant tables into a single pass. + +## Growth + +This library grows with mission lessons learned. When a mission discovers a new failure pattern not already covered, add it to the relevant category table. If the pattern does not fit an existing category, create a new H2 section following the same table format. + +## Cross-References + +- `admiralty-templates/red-cell-review.md` — Review template used alongside this library. +- `action-stations.md` — Station tier definitions that determine when red-cell participation is required. diff --git a/skills/nelson/references/sailing-orders-wizard.md b/skills/nelson/references/sailing-orders-wizard.md new file mode 100644 index 0000000..b5aa375 --- /dev/null +++ b/skills/nelson/references/sailing-orders-wizard.md @@ -0,0 +1,102 @@ +# Sailing Orders Wizard + +An interactive scaffold that guides users through creating complete sailing orders. Instead of presenting a blank template, the wizard asks structured questions and populates the template from the answers. This reduces the barrier to writing good sailing orders, especially for first-time users who face unfamiliar fields like "outcome," "success metric," and "stop criteria." + +## Purpose + +The sailing orders template at `admiralty-templates/sailing-orders.md` is comprehensive but can feel daunting when empty. The wizard walks the user through each field with a plain-language question, validates the answers, and assembles the completed template. The result is a fully populated set of sailing orders ready for the admiral to issue. + +## Quick vs. Full Mode + +| Mode | Questions | When to Use | +|---|---|---| +| Quick | 1-3 only | Small missions, familiar users, low ambiguity | +| Full | 1-7 all | Complex missions, first-time users, high stakes | + +In quick mode, questions 4-7 receive sensible defaults (see Defaults and Validation below). The admiral may always override defaults before issuing orders. + +## Wizard Questions + +Ask these questions in order. Map each answer to the corresponding sailing orders field. + +| Step | Question | Populates | +|---|---|---| +| 1 | "What should be different when this mission is done?" | Outcome | +| 2 | "How will we know it worked? What is the measurable result?" | Success Metric | +| 3 | "When does this need to be done?" | Deadline | +| 4 | "What must NOT happen? Any forbidden actions or safety constraints?" | Constraints | +| 5 | "What is explicitly out of scope?" | Out of Scope | +| 6 | "When should we stop, even if not everything is done?" | Stop Criteria | +| 7 | "What artifacts must exist at the end?" | Handoff Artifacts | + +### Guidance for Each Question + +**Step 1 — Outcome.** Push for a concrete end state, not an activity. "Refactor the auth module" is an activity. "Auth module uses token-based sessions with all existing tests passing" is an outcome. + +**Step 2 — Success Metric.** The metric must be independently verifiable. Ask: "Could someone who was not involved confirm this was achieved?" If the answer is no, the metric needs sharpening. + +**Step 3 — Deadline.** Accept a specific time, a session boundary, or a token budget. If the user is unsure, default to "End of session." + +**Step 4 — Constraints.** Prompt for forbidden actions, safety rails, and budget limits. If the user has none, apply the default. + +**Step 5 — Out of Scope.** The admiral should name at least one exclusion. An empty out-of-scope section is a leading indicator of scope drift. If the user offers nothing, suggest boundaries based on the stated outcome. + +**Step 6 — Stop Criteria.** Must be concrete and testable. "When it feels done" is not a stop criterion. "When all 14 endpoints return 200 on the integration test suite" is. + +**Step 7 — Handoff Artifacts.** Name the files, documents, or states that must exist when the mission is complete. This is what the admiral inspects at stand-down. + +## Defaults and Validation + +### Defaults + +Apply these when a question is skipped or the user has no answer. + +| Field | Default | +|---|---| +| Deadline | "End of session" | +| Constraints | "Standard Nelson standing orders apply" | +| Out of Scope | Admiral should suggest at least one exclusion based on the stated outcome | +| Stop Criteria | Derived from the success metric — "Stop when the success metric is met or the deadline is reached" | +| Handoff Artifacts | Derived from the outcome — the minimum artifacts that prove the outcome was achieved | + +### Validation Rules + +Run these checks before assembling the final sailing orders. + +| Rule | Check | Remedy | +|---|---|---| +| Outcome and metric are distinct | Compare outcome (Step 1) and metric (Step 2) for duplication | If they are identical or near-identical, ask: "The outcome and metric look the same. Can you give a metric that someone else could independently verify?" | +| Stop criteria are testable | Confirm stop criteria contain a concrete condition | If vague, ask: "How would we know this condition has been met? Can you make it more specific?" | +| Out of scope is not empty | Confirm at least one exclusion exists | If empty, suggest: "Based on the outcome, consider excluding [related but tangential area]. Does that seem right?" | +| Metric is independently verifiable | Confirm the metric does not require subjective judgement | If subjective, ask: "Could someone uninvolved confirm this? What would they check?" | + +## Assembled Output + +After all questions are answered and validation passes, assemble the completed sailing orders using the template from `admiralty-templates/sailing-orders.md`. + +```text +Sailing orders: +- Outcome: [Step 1 answer] +- Success metric: [Step 2 answer] +- Deadline: [Step 3 answer or default] + +Constraints: +- Token/time budget: [from Step 3 or Step 4] +- Reliability floor: [from Step 4 if applicable] +- Compliance/safety constraints: [from Step 4 if applicable] +- Forbidden actions: [from Step 4 if applicable] + +Scope: +- In scope: [derived from Step 1] +- Out of scope: [Step 5 answer or suggested exclusion] + +Stop criteria: +- Stop when: [Step 6 answer or derived default] + +Required handoff artifacts: +- Must produce: [Step 7 answer or derived default] +``` + +## Cross-Reference + +- `admiralty-templates/sailing-orders.md` — the template this wizard populates. diff --git a/skills/nelson/references/squadron-metrics.md b/skills/nelson/references/squadron-metrics.md new file mode 100644 index 0000000..d06cf51 --- /dev/null +++ b/skills/nelson/references/squadron-metrics.md @@ -0,0 +1,113 @@ +# Squadron Metrics Framework + +Six measures of squadron performance, drawn from existing captain's log fields. These metrics give the admiral a quantitative picture of mission health alongside the qualitative quarterdeck reports. No new tooling is required — all values are extractable from data already recorded during normal operations. + +## Metrics Overview + +| Metric | RN Name | What It Measures | How to Calculate | +|---|---|---|---| +| Mission success rate | **Homecoming Rate** | Percentage of missions achieving their stated outcome | Successful missions / Total missions | +| Token efficiency | **Coal Consumption** | Tokens spent per completed task | Total tokens / Completed tasks | +| Time to first output | **Anchor to Sail** | Duration from sailing orders to first deliverable | Timestamp of first task completion - Mission start time | +| Blocker resolution speed | **Signal Clarity** | Average time from blocker raised to blocker resolved | Sum of resolution times / Number of blockers | +| Verification pass rate | **Dock Inspection** | Percentage of tasks passing validation on first attempt | First-pass validations / Total validations | +| Hull integrity at stand-down | **Seaworthiness Index** | Average hull integrity across the squadron at mission end | Average of all ships' final hull integrity percentage | + +## Metric Definitions + +### Homecoming Rate + +A mission is successful when it achieves the outcome stated in the sailing orders. Partial completion counts as a failure for this metric — the sailing orders define the bar, not the effort expended. + +Record the outcome (success or failure) in the captain's log at stand-down. Over multiple missions, the homecoming rate reveals whether sailing orders are being scoped realistically and whether the squadron is executing effectively. + +**Healthy range:** Above 80%. A consistently low homecoming rate suggests sailing orders are too ambitious for the squadron size, or that blocker resolution is too slow. + +### Coal Consumption + +Measures how efficiently the squadron converts tokens into completed work. High coal consumption may indicate confusion, rework, standing order violations, or poor task decomposition. + +Calculate by dividing total tokens consumed across all ships by the number of tasks marked complete in the battle plan. + +**Healthy range:** Below 5,000 tokens per task. Spikes in coal consumption warrant investigation — check for crew overruns, idle crew, or ships operating at Condition ZEBRA for extended periods. + +### Anchor to Sail + +The interval between the admiral issuing sailing orders and the first verified deliverable landing. A long anchor-to-sail time may indicate over-planning, unclear orders, or slow squadron formation. + +Measure from the timestamp of the sailing orders to the timestamp of the first task completion recorded in the captain's log. + +**Healthy range:** Dependent on mission scope. For small missions, under 10 minutes. For medium missions, under 20 minutes. If the squadron consistently takes longer, review whether the battle plan phase is introducing unnecessary deliberation. + +### Signal Clarity + +When a blocker is raised (by any agent, at any level), the clock starts. When the blocker is resolved — by the admiral, by another captain, or by the blocking agent itself — the clock stops. Signal clarity is the average of all blocker durations in a mission. + +Low signal clarity indicates that blockers are being raised but not surfaced, acknowledged, or resolved promptly. This is often an admiral coordination problem rather than a captain execution problem. + +**Healthy range:** Below 5 minutes per blocker. Persistent slow resolution suggests the admiral is too deep in implementation (see `standing-orders/admiral-at-the-helm.md`) or that the quarterdeck rhythm interval is too long. + +### Dock Inspection + +The percentage of tasks that pass their verification criteria on the first attempt. A low dock inspection rate means rework is consuming squadron capacity — ships are spending tokens fixing outputs rather than producing new ones. + +Record pass or fail for each task's first verification attempt in the captain's log. Calculate the ratio at stand-down. + +**Healthy range:** Above 70%. Below this threshold, review whether verification criteria are clear in the battle plan, whether captains are self-verifying before reporting completion, and whether crew roles include adequate quality assurance. + +### Seaworthiness Index + +At stand-down, record each ship's final hull integrity percentage. The seaworthiness index is the average across all ships. This measures whether the squadron is finishing missions with capacity to spare or routinely running ships into ZEBRA and ZEBRA (Critical). + +A low seaworthiness index across multiple missions suggests the squadron is undersized for the work being assigned, or that relief on station is being triggered too late. + +**Healthy range:** Above 50% average hull integrity at stand-down. If the squadron routinely finishes below this, consider adding ships or reducing mission scope. + +## Collection + +Start with these five lightweight metrics that require no tooling beyond the existing captain's log: + +1. **Homecoming Rate** — Recorded as a success/failure flag at stand-down. +2. **Coal Consumption** — Derived from token usage (already tracked for hull integrity) and task completion count. +3. **Dock Inspection** — Recorded as pass/fail on first verification per task. +4. **Seaworthiness Index** — Derived from final damage reports (already filed for hull integrity monitoring). +5. **Signal Clarity** — Derived from blocker timestamps in quarterdeck reports. + +**Anchor to Sail** requires timestamp recording that may not be present in all captain's log entries. Add it when the logging practice matures. + +All collection is manual during initial adoption. The admiral records metric values in the captain's log at stand-down. No automated extraction is required at this stage. + +## Reporting + +Metrics are recorded in the captain's log under a dedicated **Squadron Performance** section at stand-down. A minimal entry looks like: + +``` +## Squadron Performance + +- Homecoming Rate: 1/1 (100%) +- Coal Consumption: ~3,200 tokens/task +- Dock Inspection: 8/10 first-pass (80%) +- Seaworthiness Index: 62% average hull integrity +- Signal Clarity: 3 blockers, avg 4 min resolution +``` + +Over time, the **nelson-metrics** companion plugin (see `companion-plugins.md`) can parse these entries and aggregate metrics across missions, generating trend reports and identifying systemic issues. + +## Benchmarks + +| Metric | Healthy | Warning | Critical | +|---|---|---|---| +| Homecoming Rate | > 80% | 60 -- 80% | < 60% | +| Coal Consumption | < 5,000 tokens/task | 5,000 -- 10,000 tokens/task | > 10,000 tokens/task | +| Anchor to Sail | < 10 min (small) / < 20 min (medium) | 2x healthy range | > 3x healthy range | +| Signal Clarity | < 5 min/blocker | 5 -- 15 min/blocker | > 15 min/blocker | +| Dock Inspection | > 70% | 50 -- 70% | < 50% | +| Seaworthiness Index | > 50% | 30 -- 50% | < 30% | + +When a metric falls into the warning range, the admiral should investigate at the next quarterdeck checkpoint. When a metric reaches critical, the admiral should address it as a standing agenda item until it recovers. + +## Cross-References + +- `admiralty-templates/captains-log.md` — Template where metrics are recorded at stand-down. +- `companion-plugins.md` — The nelson-metrics companion plugin for cross-mission aggregation. +- `damage-control/hull-integrity.md` — Source data for the Seaworthiness Index and Coal Consumption metrics. diff --git a/skills/nelson/references/standing-order-troubleshooter.md b/skills/nelson/references/standing-order-troubleshooter.md new file mode 100644 index 0000000..2dd4fdf --- /dev/null +++ b/skills/nelson/references/standing-order-troubleshooter.md @@ -0,0 +1,64 @@ +# Standing Order Troubleshooter + +Use when you observe a problem during a mission but are not sure which standing order addresses it. Work through the symptom categories below to identify the correct standing order, then load and apply it. + +## Work Distribution Problems + +Problems with how work is spread across the squadron. + +- **Most agents are idle while one or two are overloaded** -- The squadron may be too large for the mission scope. See `standing-orders/becalmed-fleet.md`. +- **An agent was added but has no meaningful work** -- A ship was launched without canvas to fill. See `standing-orders/crew-without-canvas.md`. +- **Every role is crewed regardless of whether the task warrants it** -- Over-crewing wastes budget and adds coordination overhead. See `standing-orders/all-hands-on-deck.md`. +- **A single crew member was spawned for an atomic task** -- One crew member adds overhead without parallelism. See `standing-orders/skeleton-crew.md`. + +## Scope and Authority Problems + +Problems with mission drift, unclear authority, or leaders doing the wrong work. + +- **Task scope is drifting from the original sailing orders** -- The anchorage is dragging. See `standing-orders/drifting-anchorage.md`. +- **The admiral is writing code or editing files instead of coordinating** -- The admiral has left the quarterdeck. See `standing-orders/admiral-at-the-helm.md`. +- **Unclear who has decision authority for a contested area** -- The chain of command has a break. See `standing-orders/chain-break.md`. +- **A captain is implementing tasks directly when crew should be doing the work** -- The captain is at the capstan. See `standing-orders/captain-at-the-capstan.md`. + +## Coordination Problems + +Problems with how agents communicate and synchronise. + +- **Multiple agents are unknowingly doing the same work** -- Ghost crews are duplicating effort. See `standing-orders/ghost-crews.md`. +- **Multiple agents are interpreting the same order differently** -- Signals are crossing. See `standing-orders/crossing-signals.md`. +- **Tasks are blocking each other in a circular dependency** -- The tides are running in circles. See `standing-orders/circular-tides.md`. + +## Quality and Context Problems + +Problems with output quality degrading or context going stale. + +- **Output quality is degrading silently over time** -- The tether is fraying. See `standing-orders/fraying-tether.md`. +- **An agent is working with stale context from an earlier phase** -- The watch has gone silent. See `standing-orders/silent-watch.md`. +- **Critical context is lost during handoffs between agents or sessions** -- The tidal pull is carrying information away. See `standing-orders/tidal-pull.md`. + +## Task and Dependency Problems + +Problems with task sizing, structure, or blocking dependencies. + +- **Tasks are too large, too vague, or too interdependent** -- A storm surge of poorly scoped work. See `standing-orders/storm-surge.md`. +- **A low-priority blocker is holding up high-value work** -- Time to cut the line. See `standing-orders/cutting-the-line.md`. + +## Role Violations + +Problems with agents or crew working outside their assigned roles. + +- **Crew are assigned work outside their defined role** -- Pressed into the wrong service. See `standing-orders/pressed-crew.md`. +- **The red-cell navigator has been assigned implementation work** -- The navigator has been press-ganged. See `standing-orders/press-ganged-navigator.md`. +- **Marines are being used for sustained crew work instead of short sorties** -- A battalion has gone ashore. See `standing-orders/battalion-ashore.md`. + +## Risk Classification + +Problems with missing or incorrect action station tiers. + +- **Tasks are proceeding without a risk tier classification** -- An unclassified engagement. See `standing-orders/unclassified-engagement.md`. + +## File Conflicts + +Problems with file ownership collisions. + +- **The same file is assigned to multiple agents** -- The keel is split. See `standing-orders/split-keel.md`. diff --git a/skills/nelson/references/standing-orders/chain-break.md b/skills/nelson/references/standing-orders/chain-break.md new file mode 100644 index 0000000..3b77db2 --- /dev/null +++ b/skills/nelson/references/standing-orders/chain-break.md @@ -0,0 +1,10 @@ +# Standing Order: Chain Break + +Do not leave decision authority ambiguous when issues arise. + +**Symptoms:** +- Multiple agents make contradictory decisions on the same issue. +- Blockers persist because no one feels empowered to resolve them. +- Trivial decisions are escalated to the admiral, stalling the fleet. + +**Remedy:** The battle plan must assign clear decision authority for each domain of the mission. Captains own decisions within their assigned deliverables; the admiral owns cross-cutting and architectural decisions. When authority is disputed, the admiral resolves it immediately at the next quarterdeck checkpoint and updates the battle plan to prevent recurrence. diff --git a/skills/nelson/references/standing-orders/circular-tides.md b/skills/nelson/references/standing-orders/circular-tides.md new file mode 100644 index 0000000..3cc67e4 --- /dev/null +++ b/skills/nelson/references/standing-orders/circular-tides.md @@ -0,0 +1,10 @@ +# Standing Order: Circular Tides + +Do not allow circular dependencies or deadlocks to form between tasks. + +**Symptoms:** +- Tasks remain in pending or blocked state indefinitely with no resolution path. +- Agents report waiting on each other, forming a cycle no one can break. +- No forward progress is made despite available budget and willing crews. + +**Remedy:** When a dependency cycle is detected, the admiral must intervene to break it. One task in the cycle should be re-scoped to remove or stub its dependency, allowing the chain to advance. If no task can be cleanly unblocked, escalate to the admiral to re-sequence the battle plan and assign a captain to resolve the bottleneck directly. diff --git a/skills/nelson/references/standing-orders/crossing-signals.md b/skills/nelson/references/standing-orders/crossing-signals.md new file mode 100644 index 0000000..11d7916 --- /dev/null +++ b/skills/nelson/references/standing-orders/crossing-signals.md @@ -0,0 +1,10 @@ +# Standing Order: Crossing Signals + +Do not issue orders that are vague enough for agents to interpret differently. + +**Symptoms:** +- Parallel work streams diverge because captains understood the same instruction differently. +- Deliverables from separate ships do not align or integrate cleanly. +- Agents ask clarifying questions that reveal contradictory assumptions about the task. + +**Remedy:** When ambiguity is detected, halt the affected work and re-issue the order with explicit acceptance criteria. The admiral must confirm that all captains share the same understanding before work resumes. Orders should name specific files, formats, and expected outputs rather than relying on implied intent. diff --git a/skills/nelson/references/standing-orders/cutting-the-line.md b/skills/nelson/references/standing-orders/cutting-the-line.md new file mode 100644 index 0000000..0046e0d --- /dev/null +++ b/skills/nelson/references/standing-orders/cutting-the-line.md @@ -0,0 +1,10 @@ +# Standing Order: Cutting the Line + +When a low-priority blocker holds up high-value work, a captain may request permission to proceed in parallel. + +**When to Signal:** +- A blocking dependency is low priority but the dependent task is high value or time-critical. +- The rework risk from proceeding without the blocker is bounded and understood. +- Waiting would waste significant budget or miss the deadline. + +**Procedure:** Captain signals the admiral with a risk assessment: what could change, what rework would be needed, and the cost of waiting vs. proceeding. Admiral approves or denies. If approved, red-cell navigator reviews the risk assessment. Captain proceeds with explicit acknowledgement that rework may be required when the blocker eventually completes. diff --git a/skills/nelson/references/standing-orders/fraying-tether.md b/skills/nelson/references/standing-orders/fraying-tether.md new file mode 100644 index 0000000..cea82ec --- /dev/null +++ b/skills/nelson/references/standing-orders/fraying-tether.md @@ -0,0 +1,10 @@ +# Standing Order: Fraying Tether + +Do not allow output quality to degrade silently until it compounds into a serious problem. + +**Symptoms:** +- Increasing rework is required on deliverables that previously passed review. +- Validation failures appear late in the mission, far from where the defect was introduced. +- Downstream tasks reject upstream outputs due to accumulated quality drift. + +**Remedy:** Institute regular quality checks at each quarterdeck checkpoint rather than deferring all validation to the end. When rework rates increase, reduce the scope of the next deliverable and tighten review criteria. The red-cell navigator should be tasked with spot-checking intermediate outputs before they propagate downstream. diff --git a/skills/nelson/references/standing-orders/ghost-crews.md b/skills/nelson/references/standing-orders/ghost-crews.md new file mode 100644 index 0000000..28f1b77 --- /dev/null +++ b/skills/nelson/references/standing-orders/ghost-crews.md @@ -0,0 +1,10 @@ +# Standing Order: Ghost Crews + +Do not allow multiple agents to unknowingly work on the same deliverable. + +**Symptoms:** +- Parallel outputs from different ships overlap significantly in content or function. +- Merge conflicts appear on files not explicitly assigned to multiple captains. +- Redundant validation or duplicate solutions emerge during quarterdeck review. + +**Remedy:** The admiral must maintain clear file ownership in the battle plan so that no deliverable is claimed by more than one ship. When duplicate work is discovered, halt the later effort immediately, retain the more advanced output, and reassign the freed captain to unblocked work. Quarterdeck checkpoints should include a brief ownership review to catch ghost crews early. diff --git a/skills/nelson/references/standing-orders/silent-watch.md b/skills/nelson/references/standing-orders/silent-watch.md new file mode 100644 index 0000000..8679657 --- /dev/null +++ b/skills/nelson/references/standing-orders/silent-watch.md @@ -0,0 +1,10 @@ +# Standing Order: Silent Watch + +Do not continue working with stale context when the situation has changed. + +**Symptoms:** +- Agent references decisions that have been superseded by later orders. +- Deliverables are built against old requirements that no longer apply. +- Output contradicts recent changes made by other captains. + +**Remedy:** Before resuming work after any pause or handoff, refresh context by reviewing the latest quarterdeck checkpoint, battle plan amendments, and captain's log entries. If in doubt, signal the admiral to confirm current orders before proceeding. diff --git a/skills/nelson/references/standing-orders/storm-surge.md b/skills/nelson/references/standing-orders/storm-surge.md new file mode 100644 index 0000000..a3325bc --- /dev/null +++ b/skills/nelson/references/standing-orders/storm-surge.md @@ -0,0 +1,10 @@ +# Standing Order: Storm Surge + +Do not assign tasks that are too large, too vague, or too interdependent for a single agent to deliver. + +**Symptoms:** +- Agent produces no output for extended periods despite being actively working. +- Requests for clarification increase as the agent struggles to define boundaries. +- Partial outputs do not integrate with the larger mission because the task was not properly scoped. + +**Remedy:** Break large tasks into deliverables that a single captain can complete within one context window. Each task must have a named output, clear acceptance criteria, and no more than two dependencies. If a captain signals that a task is too large, the admiral must re-decompose it before work continues. diff --git a/skills/nelson/references/standing-orders/tidal-pull.md b/skills/nelson/references/standing-orders/tidal-pull.md new file mode 100644 index 0000000..1c839f1 --- /dev/null +++ b/skills/nelson/references/standing-orders/tidal-pull.md @@ -0,0 +1,10 @@ +# Standing Order: Tidal Pull + +Do not allow critical context to be lost when work transfers between agents. + +**Symptoms:** +- Replacement agent repeats work that the predecessor already completed. +- The same mistakes recur after a handoff because lessons were not carried forward. +- Agents ask questions that were already answered in a previous session. + +**Remedy:** Every handoff must include a turnover brief covering completed work, known issues, open decisions, and remaining tasks. The outgoing agent is responsible for producing the brief; the incoming agent must confirm receipt and understanding before commencing work. Use the turnover brief template in the admiralty templates to ensure nothing is omitted.