power-coding

---
name: power-coding
description: >
  Mindful-coding OS for any LLM coding agent — faster, quality, scalable output. One
  invoke configures seven layers (0–6): (0) BRIEF — optional one-page PRD.md (skipped
  if design.MD/README already covers it, or on request), plus git init, gitignore, and
  a day-one security baseline;
  (1) HARNESSING — Handoff.MD (user-picked sections, one
  magic phrase chains sessions, updated on concrete events — before every commit / end of
  every phase — with a line/item compaction cap and a last-synced sha for concurrent-session
  reconcile) + auto Learning.MD for bugs and flow changes; (2) LOOP ENGINEERING — Loop.MD with evals drafted from the
  project's brief, and a status machine that offers to "turn on the loop" once the
  first draft works; (3) VIBE DEBUGGING — Mermaid flow diagrams to a strict convention,
  optionally a temp local-only in-app debug tab;
  (4) FMEA — product-aware failure-mode scans (Severity×Occurrence×Detection→RPN,
  P0/P1/P2) cross-referencing diffs against the PRD and architecture, on
  feature-complete, pre-commit, smart-suggest, or manual triggers; (5) SENTINEL SCAN —
  silent four-lens sweep after major completions (misuse traps, stop signals, silent
  failures, waste) with inline one-line flags only; (6) SESSION PULSE — 2-line effort
  split (feature/support/rework) after major milestones with one specific takeaway. Use
  on "power coding", "mindful coding", "work across sessions", "run fmea", "scan for
  failures", "run sentinel", "session pulse", "add debug diagrams", or any repo with
  Handoff.MD/.power-coding when sessions start, features complete, commits happen, or
  context runs low.
---

# Power Coding

Seven layers (0–6) that make an AI-assisted project fast, debuggable, and resumable — for any
coding agent (Claude Code, Codex, Gemini CLI…), because everything lives in plain
markdown files the agent re-reads every session. Together they implement **the Five
Forces of Mindful Coding**: *Alignment* counters ambiguity (brief, architecture
sign-off, decisions, scope brake), *Memory* counters amnesia (Handoff, Learning,
checkpoints), *the Loop* counters drift (evals → tests), *Sight* counters opacity
(diagrams, Pulse), *Foresight* counters entropy (FMEA, Sentinel, security baseline).

**How anything here happens "automatically":** agents only reliably re-read two things —
the platform's instructions file and files those instructions point to. So setup writes
one pointer block into the instructions file (`CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`;
create `AGENTS.md` if none exists), and every automatic behavior below is an instruction
stored in `Handoff.MD` / `Learning.MD` / `Loop.MD` that the pointer forces back into
context. No daemon, no hook required — redundancy of written instructions is the
mechanism.

Asking questions: use the platform's structured-question tool if one exists, otherwise
ask in plain text. If the run is non-interactive, choose sensible defaults and mark them
`⚠️ unconfirmed` for the user to review.

---

## FIRST INVOKE — configure the project (this exact order)

Detect state first: if `Handoff.MD` exists at the repo root, the project is already
configured — skip to **Ongoing duties** (and offer to re-run any single layer if the
user asked for that).

### Layer 0 — Brief (OPTIONAL — the product context everything else reads)

Loop.MD evals are drafted from the brief and FMEA scans cross-reference it. Detect
first: if the repo already has a real brief (`PRD.md`, `docs/prd*`, `design.MD`, or a
README that genuinely describes the product — not just install steps), confirm it with
the user and use it as-is: **no interview, no PRD.md created**. Only if nothing
qualifies, OFFER the brief — never force it:

> "I couldn't find a product brief (no design.MD or README with product detail). A
> one-page PRD.md makes the evals and failure scans product-aware instead of generic —
> want to answer 4 quick questions to create one?
> (a) What are you building, in one or two sentences?
> (b) Who uses it, and for what?
> (c) What must NEVER break — where would a failure cost money, data, or trust?
> (d) What does 'done' for v1 look like — the smallest version that proves it works?
> Or **skip** — you can add it anytime with `power-coding brief`."

Answered → write `PRD.md` from `assets/PRD.template.md` (plain language, one page max);
it becomes `context_sources.prd_path` in 4b. Skipped → leave `prd_path` null, draft
Loop.MD evals from the user's stated goal instead, and prefix every FMEA scan output
with one line: "⚠️ running without product context — findings are code-level only".
Non-interactive run → draft PRD.md from the code and README, mark every section
`⚠️ unconfirmed`.

**Also at Layer 0: make the repo safe to iterate in.** If there is no git repo, `git
init` and make an initial commit (tell the user why: checkpoints are the rollback path
when a change breaks the app). If there is no `.gitignore`, create one covering `.env*`,
build output, and dependency folders BEFORE the first commit — a secret committed once
is compromised forever, even if deleted later.

### Layer 1 — Harnessing (session continuity)

**1a. Create `Handoff.MD`** from `assets/HANDOFF.template.md`, then ask (multi-choice,
multi-select):

> "I've built **Handoff.MD** so you can work across multiple sessions seamlessly.
> What would you like in it?
> (a) Compact summary of the previous session's work
> (b) Current state
> (c) Pending points
> (d) Anything else — tell me"

Build exactly the sections chosen (for an existing repo, pre-fill them from a scan of
the code, git log, and any docs; for a new project, fill from the user's description of
what they're building). Then tell the user, verbatim enough to be copy-pastable:

> "From now on, to continue in a fresh session just type:
> **Refer to Handoff.MD in `<absolute project path>` and begin**
> The new session will open with your pending points (if any) or ask what you'd like
> to do next."

**1b. Standing session rules** (these also get written into Handoff.MD's header so any
agent that reads the file inherits them):

- Update Handoff.MD on **concrete events the model can actually detect** — not "after
  every major change" judged by feel: **before every git checkpoint commit** (1b's commit
  discipline makes this deterministic) and **at the end of every phase/milestone**.
  Rewrite as a current-state snapshot, don't append a journal; re-stamp `last-synced` with
  the new HEAD sha.
- **Low context is a *secondary* trigger, not the primary one.** The model can't reliably
  measure "10% remaining", so don't rely on it — but if the platform *does* signal context
  is low (compaction warning, near limit): update Handoff.MD immediately and tell the user:
  > "Context is nearly full — Handoff.MD is up to date. Please start a fresh session
  > with: *Refer to Handoff.MD in `<path>` and begin*."
- **Compaction cap (concrete heuristic, mechanical not aspirational):** when Handoff.MD
  exceeds **~40 lines** OR the Current state has **~15+ ✅ items**, collapse all ✅ into ONE
  line — `✅ Shipped: <short range> (see git log & Learning.MD)` — and push any detail to
  Learning.MD. `node <skill-path>/scripts/sentinel.mjs pulse` flags this as `⚠ compact`.
- **Concurrent-session reconcile:** Handoff carries `last-synced: <sha>`. A session that
  **starts** (magic phrase, or any repo containing Handoff.MD) must read it fully, then
  FIRST run `git log --oneline <last-synced>..HEAD` — anything there changed underneath the
  file (another session, a linter, a teammate); reconcile it before trusting the state.
  Then open with the pending points ("Last time these were pending: … — continue, or
  something else?") or, if none, "What would you like to do now?"
- **Git checkpoints:** commit whenever the app reaches a working state, and always
  *before* a risky change (refactor, dependency upgrade, schema/data migration). Never
  leave a working state uncommitted — the checkpoint is the rollback path when the next
  change breaks the app, and rollback beats a debugging spiral. Because commits mutate
  repo state, ask ONCE at setup: "**auto** — I commit checkpoints myself and announce
  each in one line — or **propose** — I ask before each one?" (recommend auto; a
  proposed-but-ignored checkpoint protects nobody). Store as
  `consent.git_checkpoints: "auto" | "propose"` in `.power-coding/config.json`.
- **Scope brake:** before starting any feature, state the smallest version that proves
  it works (measured against PRD.md's "Done for v1") and build that first — checkpoint,
  then extend. Extensions the user didn't ask for are waste, not initiative.
- **Decision log:** any decision that shapes stack, architecture, or product behavior
  gets one line in Handoff.MD's `Decisions` section (date — what — why). Never silently
  reverse a logged decision — surface the conflict and ask; if the section outgrows the
  one-screen rule, move older entries to `docs/DECISIONS.md` and keep a pointer.

**1c. Create `Learning.MD`** from `assets/LEARNING.template.md` — auto-enabled. It is
read AND updated whenever: the basic flow of the app changes, the user reports a bug or
gives corrective feedback, or something took real time to figure out. Each entry follows
the template's 5-whys format: the symptom, a Why-chain drilled until the deepest why
(typed `code` / `design` / `process` / `knowledge-gap`), the action taken (and which
"why" level it targeted), and a preventive action for the whole class of bug. Tell the
user:

> "I've also enabled **Learning.MD** — I'll log flow changes, bugs you report, and
> their root causes there, so future sessions don't repeat them. Say the word if you'd
> rather not have it."

**1d. Write the pointer block** into the instructions file (this is what makes 1b, 1c,
and Layer 2's automation survive every future session):

```markdown
## Power Coding (auto — do not remove without asking the user)
At session start read Handoff.MD; FIRST run `git log --oneline <its last-synced sha>..HEAD`
and reconcile anything changed underneath it; then open with its pending points. Update
Handoff.MD before every git checkpoint commit and at the end of every phase (low context is
a secondary trigger) — snapshot not journal, re-stamp `last-synced` with HEAD; then, if
context was the trigger, tell the user to start fresh ("Refer to Handoff.MD in <path> and
begin"). When Handoff exceeds ~40 lines or ~15 ✅ items, collapse ✅ into one "Shipped:" line,
detail to Learning.MD.
Log flow changes / user-reported bugs in Learning.MD (5-whys entry format).
Read Loop.MD every session and obey its `status:` machine — when the first working
draft is done, ASK the user whether to turn the loop on (disclosing the free/paid eval
split); while `status: on`, run the FREE Loop.MD evals after every meaningful change
and report per-eval pass/fail. The golden set / paid evals run ONLY per
consent.paid_evals (ask by default — offer at milestones, never auto per-change).
Keep docs/mermaid/*.mmd current when the flow changes (see docs/ARCHITECTURE_FLOW.md).
Obey .power-coding/config.json FMEA triggers: on_pre_commit ALWAYS runs the secret scan
first (`node <skill>/scripts/secret-scan.mjs --staged`) and BLOCKS the commit on a hit, then
a light FMEA on the staged diff (P0 → block and ask); if on_feature_complete, full scan when
a feature is declared done; if smart_suggest, suggest a scan at a natural pause when its
signals fire (never twice for an unchanged HEAD — the change-set is the git range since
state.last_fmea_commit). FMEA is pinned to a sha ("analyzed at <sha>"); re-stamp
state.last_fmea_commit after. The config's failure_categories list is the mandatory checklist.
If sentinel is enabled in .power-coding/config.json, run the four-lens Sentinel Scan
silently after every major task completion — flag only what fires, one line each.
If session_pulse is enabled, show a 2-line effort split (feature/support/rework) after
major milestones and log it in Handoff.MD updates.
Commit a git checkpoint at every working state and before any risky change (obey
consent.git_checkpoints: auto = commit + one-line announce, propose = ask first).
Before starting a feature, build the smallest version that proves it works (per PRD.md's
"Done for v1"), checkpoint, then extend. Any architecture-shaping change (new service,
external dependency, data-model change, async flow) gets a plain-language delta proposal
against the current diagram and user approval BEFORE code. Log
stack/architecture/behavior decisions as one line in Handoff.MD's Decisions; never
silently reverse a logged decision. PRD.md is the product context for evals and scans —
keep it current. Full FMEA scans obey consent.fmea_full_scan (ask | auto).
```

### Layer 2 — Loop Engineering (evals that finetune the app)

Read `references/loop-engineering.md` for the full protocol. Setup steps:

**2a-0. Adopt the project's OWN tests as the cheapest rung first.** Before drafting any
eval, detect what the repo already runs (`package.json` test scripts, `pytest`/`tox`,
`go test`, `cargo test`, and the CI workflow) and record it as **Rung 1** in Loop.MD — the
existing suite IS the cheapest rung; the loop runs it before any eval. **Do not hand-author
evals that just duplicate existing tests** — reserve the eval tiers for behaviour a unit
test can't express (judgement calls: "returns a *sensible* SoV", "refuses out-of-scope
requests"). This is the inverse of eval graduation (2e): tests you already have are adopted
in; evals that mature graduate out.

**2a. Create `Loop.MD`** from `assets/LOOP.template.md`, and **draft 3–6 example FREE
evals from the project itself** — read the brief/README/docs `.md` files (existing
project) or the user's stated goal (new project) and write concrete Q→expected-A pairs
(for an agentic system: input → expected behavior; for an app: action → expected
result). These are labelled EXAMPLES. **Then classify the product:** if its core output
is LLM-generated or a core flow calls paid APIs, also draft a **golden set** from the
brief (8–12 samples: typical, hard/edge, must-refuse; each with a check method —
exact / contains / rubric) and set `consent.paid_evals: "ask"` in the config. See
"Golden set" and "Cost consent" in `references/loop-engineering.md`.

**2b. Ask the user to make it theirs:**

> "**Loop.MD** is ready with example evals drafted from your project docs. Please edit
> it: state your goal for the app, and replace/extend the examples with real
> questions-and-expected-answers. These become the yardstick the loop finetunes
> against."

**2c. The automatic loop offer.** Loop.MD carries `status: waiting_for_first_draft` and
an agent instruction block. The moment the agent completes a **first working draft**
(the core path runs end-to-end once), it must ask:

> "First draft is working. Want me to **turn on the Loop**? After each change I'll run
> the free evals in Loop.MD (they cost nothing), show you per-eval pass/fail, and keep
> finetuning until they pass. The golden set costs real API money — I'll only run it
> when you approve or at milestones."

The cost split in that offer is mandatory, not optional wording — turning the loop on
consents ONLY to free evals; paid runs stay per-approval (`consent.paid_evals`).

User says yes → `status: on`. This trigger is stored in three places on purpose
(pointer block, Loop.MD itself, and a Handoff.MD pending item "offer the loop when
first draft is ready") so it fires even sessions later, on any LLM.

**2d. While the loop is on:** after each meaningful change — cheapest checks first
(typecheck/tests if the repo has them), then walk the FREE Loop.MD evals, report a
per-eval ✅/❌ table, fix, repeat. The golden set NEVER runs automatically per-change:
per `consent.paid_evals`, offer it at milestones ("feature complete — run the golden
set? ~N paid calls") or on request. Any paid run gets a one-line written hypothesis in
Loop.MD's run journal *before* running, and failures get reproduced as free checks
before re-spending — never use a paid check as a debugger.

**2e. Eval graduation (the loop matures into a test suite):** when an eval has passed
3 consecutive loop runs, offer to codify it as an automated test in the repo's stack —
creating the minimal test setup first if none exists (one test runner, one example
test, a one-line run command; explain what it's for, since the user may never have had
one). A graduated eval is marked `(graduated → <test file>)` in Loop.MD and runs in
step "cheapest first" instead of the manual walkthrough — the loop gets *faster* as the
app matures, and the user ends up with a real regression suite without ever being asked
to "write tests".

### Layer 3 — Vibe Debugging (see the flow instead of reading code)

Ask exactly this and wait:

> "For debugging, do you want **(A)** only Mermaid `.mmd` diagram files (+ a standalone
> HTML viewer), or **(B)** also a **temporary, local-only debug tab inside the app**
> that renders them live?"

Then execute the diagram protocol — read `references/diagram-convention.md` and follow
it exactly:

1. **Discover** the real runtime flow by reading entry points and tracing the main path
   (never guess). Classify each step AGENT / FUNCTION / LIBRARY / DATA with its in/out.
2. **Author** `docs/mermaid/NN-title.mmd`. Start **master-only** while a phase is still
   churning (mark `%% granularity: master` — one step per box, big decisions and branches,
   cheap to keep current); expand a lane to full granularity (thresholds, AGENT/FUNCTION
   annotations, `%% granularity: full`) only once it stabilises — per-box granularity on a
   flow you're still reshaping is too heavy to maintain. Give each `.mmd` a
   **`%% files: <the source files it depicts>` header** — this is what makes staleness
   mechanical (step 6). New project with no code yet → draw the *intended* architecture,
   marked `%% intended — not yet built`.
3. **Validate**: `node <skill-path>/scripts/validate-mmd.mjs docs/mermaid`.
4. **Build the viewer**: `node <skill-path>/scripts/build-html.mjs docs/mermaid
   docs/architecture-flow.html` — dependency-free, open in any browser.
5. **(B only)** Scaffold the in-app debug tab per `references/debug-tab-recipes.md`
   (Next.js / Vite recipes; anything else → the standalone viewer). Label it visibly as
   a debug aid, keep it local-only (exclude from production builds or gate on
   `NODE_ENV !== "production"`), and verify it serves before declaring done.
6. **Staleness is detected, not just hoped for.** Diagrams are authored, not
   auto-generated — so the `%% files:` header lets the tooling flag drift instead of
   relying on you to remember: `node <skill-path>/scripts/sentinel.mjs scan` marks a
   diagram stale when any source file it depicts is newer than the `.mmd` (works for
   option A too, not just the debug tab's mtime banner). Update the `.mmd` in the same
   session as any structural change — the git diff of the `.mmd` IS the change-highlight.

**3-align. Architecture alignment (always — this step is never optional).** The user
must approve the shape of the system before code is built against it — a wrong
architecture caught at proposal time costs one conversation; caught after build, a
rewrite. The user may not read code, but they CAN judge a plain-language proposal.

- **New project:** after drawing the intended-architecture diagram, walk it in plain
  language — one line per component: *what it is, why this choice, and its main
  trade-off* ("one Postgres database — simplest thing that scales to thousands of
  users; trade-off: a single point to back up"). End with the failure the user would
  care most about ("if the server restarts mid-payment, X happens"). Then WAIT for
  approval before building. Approval → one line in Handoff.MD's `Decisions`.
- **Existing project:** after discovering the real flow (step 1), confirm it back:
  "This is how your app actually works — [3–5 plain-language lines + t

… (truncated)