p10-bridge

name	p10-bridge
description	Apply NASA's Power of 10 safety rules as a pre-execution planning contract for any engineering task. Use this skill before writing or modifying code whenever a task has been defined (via gstack, /council ruling, or direct issue). The skill researches the codebase, drafts a P10-compliant implementation plan (full task or named stage), saves it to Obsidian, and provides a decision overview. The saved draft becomes the foundation the execution agent reads before touching any file. Trigger on: "plan this with p10", "p10 draft", "bridge to execution", "safe implementation plan", any task following a /council ruling, or any gstack /plan phase where correctness and safety are non-trivial. This is the bridge between planning and elite execution — always invoke it before implementing complex, stateful, or safety-critical logic.
compatibility	{"tools":["bash_tool","Task"],"models":{"scouts":"claude-haiku-4-5-20251001","analyst":"claude-sonnet-4-6","arbiter":"claude-opus-4-8"},"environment":"Claude Code with gstack installed","obsidian":"local filesystem vault (configurable path)","upstream":"llm-council (optional — accepts /council rulings as input)"}

P10 Bridge

A pre-execution planning layer grounded in NASA JPL's Power of 10 rules. Given a task, the skill scouts the codebase, analyzes the task against each P10 rule, drafts a compliant implementation plan, passes it to Opus for arbitration, and commits the approved plan to Obsidian. The execution agent reads this draft before writing a single line — ensuring complex architecture is built on a verified, safe foundation.

---

NASA Power of 10 Rules

#	Rule	Execution constraint
1	Simple control flow	No recursion. No goto. No setjmp/longjmp.
2	Fixed loop bounds	Every loop has a provable upper bound. Annotate it.
3	No dynamic memory post-init	Heap allocation only during initialization phase.
4	Functions ≤ 60 lines	One screen, one purpose. Split if exceeded.
5	≥ 2 assertions per function	Invariants are explicit. Use assert or typed guards.
6	Minimal variable scope	Declare at narrowest scope. No wide globals.
7	Check every return value	No silent failures. Every call site handles errors.
8	Preprocessor / macro use minimal	No function-like macros. Constants over #define.
9	Restrict pointer use	No function pointers unless unavoidable. Dereference once.
10	Zero warnings	All compiler/linter warnings treated as errors.

Rules 3, 8, and 9 adapt for dynamic and modern compiled languages — see Language Adapters section below.

---

Architecture

Task Input (gstack issue / /council ruling / direct prompt)
     │
     ▼
┌─────────────────┐
│  CODEBASE SCOUT │  Haiku subagents (parallel) — map files, deps, entry points
└─────────────────┘
     │
     ▼
┌─────────────────┐
│  P10 ANALYZER   │  Sonnet — maps task against each rule, surfaces risks + constraints
└─────────────────┘
     │
     ▼
┌─────────────────┐
│  DRAFT WRITER   │  Sonnet — writes staged, P10-compliant implementation plan
└─────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────┐
│  P10 ARBITER (Opus)                                 │
│  Reads: P10 analysis + draft only (not raw scouts)  │
│  Approve → status: approved                         │
│  Revise  → Sonnet rewrites once, Opus re-reviews    │
│  Block   → status: blocked, names rule + resolution │
└─────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────┐
│  OBSIDIAN WRITE │  Haiku — commits Opus-stamped plan to vault
└─────────────────┘
     │
     ▼
Execution agent reads Obsidian draft — status: approved required to proceed

---

Workflow

Step 0 — Config Resolution

Resolve vaultPath and this skill's log/plan directory before doing anything else. Same 4-step order in every skill this plugin bundles (p10, llm-council, the-cabinet) — do not deviate, this consistency is what keeps the lookup unambiguous:

1. TOTO_VAULT_PATH env var, if set — always wins.
2. <plugin-root>/settings.local.json, if the plugin was installed via claude plugin add and the file exists.
3. Global ~/.claude/CLAUDE.md prose (the legacy convention — still honored, not removed).
4. Hardcoded default (~/.toto/vault), if nothing above resolved.

Print which source won (e.g. resolved vaultPath from: env TOTO_VAULT_PATH) before proceeding — this line is load-bearing, not cosmetic: without it, an env var silently shadowing a settings.local.json override becomes an invisible footgun.

First-run / no cached resolution beyond the hardcoded default: if there's an interactive session (TTY available), ask the user for vaultPath (and this skill's log/plan dir, if it differs from the default) via AskUserQuestion, then write the answer to <plugin-root>/settings.local.json (source #2 above) so future runs skip the prompt. If writing fails (e.g. read-only plugin dir), use the answered value for this run only and warn that the prompt will repeat next time.

No interactive session available (headless, CI, scripted claude plugin add): do NOT wait on AskUserQuestion — it has no path to a human here. Fall through to source #4 (hardcoded default) and emit a fail-loud stderr warning naming the exact remediation: set TOTO_VAULT_PATH=<path> or create <plugin-root>/settings.local.json before running in a non-interactive environment. Never proceed silently as if a value were confirmed when it wasn't.

Step 1 — Codebase Scout (Haiku, parallel subagents)

Spawn 2–4 scout subagents to map the codebase relevant to the task. Each Agent tool call MUST set these parameters explicitly — do not rely on defaults:

• model: 'claude-haiku-4-5-20251001' — inheriting the parent session's model (Sonnet/Opus) here is the single largest cost driver in this skill. Always set it.
• subagent_type: 'Explore' — scouts only read and map; they never write or edit. general-purpose's default system prompt is far larger than a scout task needs.
• Read-scope bound in the prompt itself: "Inspect at most 15 files. Do not read any file end-to-end unless the task specifically requires its full content — prefer targeted symbol/grep lookups and cite line ranges." A word cap on the response (below) does nothing if the scout still burns its budget reading unbounded input.
• Report-length bound in the prompt itself: "Report back in under 400 words, structured, file:line citations only — no full file dumps, no pasted source blocks longer than 5 lines." This is what keeps the P10 Analyzer's incoming context small.

Tool preference: When running inside Claude Code with Serena MCP registered, scouts should default to Serena's symbol-aware tools instead of grep — AST-level scouting catches structural violations (real function boundaries, actual call graphs) that text search misses:

• mcp__serena__get_symbols_overview — file-level symbol maps (Scout A, entry points)
• mcp__serena__find_symbol — locate specific functions/classes by name (Scout A, B)
• mcp__serena__find_referencing_symbols — call-graph / impact analysis (Scout B, C)

Fall back to grep-based scouting only if Serena MCP is not registered in the session.

Scout A: Find entry points and call sites related to the task scope
         (Serena: get_symbols_overview + find_symbol; fallback: grep for function
         names, imports, exports)

Scout B: Map data flow — what state is read/written by this task's scope
         (Serena: find_symbol + find_referencing_symbols; fallback: grep)

Scout C: Identify existing violations of P10 rules in affected files
         (functions > 60 lines, unchecked returns, dynamic alloc patterns —
         Serena: get_symbols_overview to get exact function boundaries/line counts;
         fallback: grep)

Scout D: Check gstack /freeze registry — flag any locked modules in scope

Scouts output a codebase snapshot: file list, relevant functions, existing violations, freeze flags. Passed to P10 Analyzer — not to the user directly.

Step 2 — P10 Analysis (Sonnet)

Agent tool call: model: 'claude-sonnet-4-6', subagent_type: 'general-purpose'. This step makes judgment calls across 10 interacting rules, not a search — a scoped search-only agent type is the wrong fit here. Cap the incoming scout context to what Step 1 already bounded; do not paste raw scout transcripts if a summary suffices.

For each of the 10 rules, assess impact on the task:

### P10 Analysis

**Rule 1 — Control flow:** [SAFE | RISK | BLOCKED] — [why]
**Rule 2 — Loop bounds:** [SAFE | RISK | BLOCKED] — [why + bound annotation if needed]
**Rule 3 — Memory:** [SAFE | RISK | N/A] — [why]
**Rule 4 — Function size:** [SAFE | RISK] — [functions at risk of exceeding 60 lines]
**Rule 5 — Assertions:** [SAFE | MISSING] — [where assertions must be added]
**Rule 6 — Scope:** [SAFE | RISK] — [variable scope concerns]
**Rule 7 — Return values:** [SAFE | RISK] — [call sites that must handle errors]
**Rule 8 — Macros:** [SAFE | N/A] — [macro usage in scope]
**Rule 9 — Pointers:** [SAFE | RISK | N/A] — [pointer/reference concerns]
**Rule 10 — Warnings:** [CLEAN | FLAGS] — [known lint/type issues in scope]

**Blocking risks:** [rules with BLOCKED status must be resolved before execution]
**Pre-conditions:** [what must be true before execution begins]

Step 3 — Draft Plan (Sonnet)

Agent tool call: model: 'claude-sonnet-4-6', subagent_type: 'general-purpose'. Drafting a staged plan is synthesis, not search — general-purpose is the right fit.

Write a staged, P10-compliant implementation plan:

## P10 Implementation Draft — [TASK TITLE]

**Task:** [one sentence]
**Stage:** [if partial — which stage of the overall plan]
**gstack phase:** [plan / review / ship]
**Council ruling ref:** [link or slug if triggered by /council]
**Date:** [ISO]

### Pre-conditions
[What must be true before execution. Verified by scout.]

### Implementation Stages

#### Stage N: [name]
- **Scope:** [files and functions touched]
- **P10 constraints active:** [rules 1–10 relevant to this stage]
- **Assertions required:** [explicit invariants to add]
- **Return value handling:** [every call site that needs a handler]
- **Loop bound annotations:** [each loop with its provable upper bound]
- **Function split plan:** [if any function risks exceeding 60 lines]
- **Freeze check:** [any locked modules — do not touch without /council]

### Decision Overview

**Why this approach:** [reasoning grounded in P10 + codebase findings]
**Alternatives rejected:** [what was considered and why discarded]
**Risk surface:** [what could still go wrong and why it's acceptable]
**Execution agent instructions:** [what the agent must read/check before starting]

One draft per task or per named stage. Multi-stage tasks: one draft per stage, linked in the Obsidian index.

Step 4 — P10 Arbiter (Opus)

Agent tool call: model: 'claude-opus-4-8', subagent_type: 'general-purpose'. Already correctly scoped to receive only the compressed analysis/draft, not raw scout output — keep it that way, this is the cheapest tier to get wrong.

Opus receives only the P10 analysis and draft plan — not raw scout output. Three valid responses:

A) Approve:

## P10 Arbiter — Approved
**Status:** approved
**Ruling:** [confirmation that plan satisfies all 10 rules]
**Conditions:** [any execution-time conditions the agent must uphold]
**Cross-rule notes:** [interactions between rules Sonnet may have missed]

B) Revision Required (once per draft):

## P10 Arbiter — Revision Required
**Status:** revision-required
**Rule(s):** [specific rules insufficiently addressed]
**Required change:** [exactly what Sonnet must fix in the draft]

After revision: Sonnet updates draft (~400 tok), Opus re-reviews. Maximum one cycle.

C) Blocked:

## P10 Arbiter — Blocked
**Status:** blocked
**Blocking rule:** [rule N — exact violation]
**Resolution required:** [what architectural decision must be made first]
**Escalation:** [/council recommended | task must be redesigned]

Blocked drafts cannot proceed. Resolution typically requires a /council session — the block reason becomes the council input.

Step 5 — Obsidian Commit (Haiku)

Uses vaultPath and p10.planDir (default P10-Plans) resolved in Step 0.

File: {vaultPath}/{p10.planDir}/YYYY-MM-DD-{task-slug}.md

Frontmatter:

---
date: YYYY-MM-DD
task: [slug]
stage: [N or "full"]
gstack_phase: [phase]
council_ref: [slug or null]
status: draft | revision-required | approved | blocked | executed | revised
arbiter_action: approved | revision-required | blocked
p10_blocking_rules: [list of BLOCKED rules, or none]
tags: [p10, planning, gstack, {domain}]
---

Update P10-Plans/INDEX.md with each new draft (date, task, stage, status).

---

gstack Integration

gstack Phase	P10 Bridge role
/plan	Primary trigger — draft P10 plan before any architecture is locked
/review	Re-run P10 analysis on PR diff; flag new violations
/ship	Verify status: approved before execution proceeds
/retro	Surface P10 violations introduced during execution; update draft status
/council ruling	Ruling becomes council_ref in the draft frontmatter

Freeze respect: If scout finds a frozen module in task scope, the draft must include: ⚠️ FROZEN: [module] — /council required before touching.

---

Execution Agent Handoff

Before writing any code, read:
{vaultPath}/{p10.planDir}/{draft-filename}.md

Verify status is `approved` and arbiter_action is `approved`.
If status is anything other than `approved` — STOP. Do not execute.
If blocked, escalate to /council. If revision-required, return to p10-bridge.

Follow the staged plan exactly. Do not exceed function size limits.
Add all annotated assertions. Handle every return value listed in the draft.
Respect all freeze flags.

---

Token Budget

Step	Model	Budget
Scout ×2–4	Haiku	~250 tok each
P10 Analyzer	Sonnet	~800 tok
Draft Writer	Sonnet	~1000 tok
P10 Arbiter	Opus	~800 tok
Revision (if needed)	Sonnet + Opus	~400 + ~500 tok
Obsidian Writer	Haiku	~300 tok

Target: ~3800–4300 tok per draft. With revision: ~4700–5200 tok.

---

Language Adapters

Rules 3, 8, and 9 do not map directly to dynamic or modern compiled languages. Scouts load the relevant section below at codebase scan time.

TypeScript / JavaScript

Rule	Adaptation
1 — Control flow	No recursion. No eval. Flatten promise chains with async/await.
2 — Loop bounds	Every for/while must have a provable bound. Comment the max count. No unbounded while(true).
3 — Memory	No unbounded data structure growth at runtime. Arrays and maps must have max-size guards.
4 — Function size	≤ 60 lines. ESLint max-lines-per-function enforced.
5 — Assertions	assert from node:assert or typed invariant helper. Min 2 per function. Type guards that throw count.
6 — Scope	const over let. let over var. No var. Module-level state must be justified.
7 — Return values	No ignored Promise rejections. Every await in try/catch or .catch(). ESLint @typescript-eslint/no-floating-promises.
8 — Macros	No eval, no Function() constructor, no dynamic require.
9 — Pointers	No any type. No unchecked type assertions (as Type without guard).
10 — Warnings	tsc --strict --noEmit clean. ESLint zero warnings. "strict": true in tsconfig.

Python

Rule	Adaptation
1 — Control flow	No recursion (or explicit sys.setrecursionlimit with documented bound). No exec. No dynamic import at runtime.
2 — Loop bounds	All while loops must document max iteration count. for over iterables preferred — document expected max length.
3 — Memory	No unbounded list/dict growth. Use collections.deque(maxlen=N) for bounded queues. Document max size for all growing structures.
4 — Function size	≤ 60 lines. flake8 --max-function-length enforced.
5 — Assertions	assert with descriptive messages. Min 2 per function. isinstance checks count.
6 — Scope	No module-level mutable state unless justified. No global without documentation.
7 — Return values	No ignored returns for functions that can fail. Never bare except:. All exceptions caught at appropriate boundary.
8 — Macros	No exec, no eval, no __import__.
9 — Pointers	All parameters and returns must have type annotations. mypy --strict must pass.
10 — Warnings	mypy --strict clean. flake8 zero warnings. pylint score ≥ 9.0.

Go

Rule	Adaptation
1 — Control flow	No recursion unless provably bounded and documented. No goto.
2 — Loop bounds	All for loops with a condition (not range) must document max iterations.
3 — Memory	No unbounded goroutine spawning. Channel buffers must be sized. Use sync.Pool for reuse.
4 — Function size	≤ 60 lines. gocyclo complexity ≤ 10.
5 — Assertions	Explicit error checks as assertions. panic with message for true invariant violations.
6 — Scope	:= at narrowest scope. Package-level vars must be justified.
7 — Return values	Every error return checked. errcheck linter enforced. No _ for error values.
8 — Macros	No unsafe package without documented justification.
9 — Pointers	Prefer value receivers. Document every pointer receiver choice.
10 — Warnings	go vet clean. staticcheck clean. golangci-lint zero warnings.

Rust

Rule	Adaptation
1 — Control flow	No recursion unless bounded. No unsafe control flow.
2 — Loop bounds	All loop blocks must document exit condition and maximum iteration bound.
3 — Memory	Ownership system enforces structurally. No unsafe allocator use. Box::new only in init paths.
4 — Function size	≤ 60 lines. clippy::too_many_lines enforced.
5 — Assertions	assert! and debug_assert! min 2 per function. No unwrap() — use expect("invariant reason").
6 — Scope	Narrowest scope always. No unnecessary mut.
7 — Return values	All Result and Option handled. No unwrap() in production paths. #[must_use] on all Result-returning functions.
8 — Macros	macro_rules! only for well-understood patterns. No proc macros without team review.
9 — Pointers	No raw pointers (*const, *mut) outside unsafe. No unsafe without /council-reviewed justification.
10 — Warnings	cargo clippy -- -D warnings clean. cargo check clean.

---

Output to User

1. Draft path — confirm file written to vault
2. Arbiter ruling — Approved / Revision Required / Blocked (prominent)
3. P10 analysis summary — any RISK or BLOCKED rules called out
4. Stage overview — what the execution agent will do, in order
5. Execution readiness — READY | BLOCKED: [rule N — reason]

---

When NOT to use this skill

• Trivial single-line fixes with no architectural surface
• Pure documentation or config changes
• Tasks already covered by an approved, unexecuted P10 draft
• Hotfixes where speed is critical — flag for post-hoc P10 review instead