Power Coding

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 `` 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 `` 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: (see git log & Learning.MD) — and push any detail to Learning.MD. node /scripts/sentinel.mjs pulse flags this as ⚠ compact.

• Concurrent-session reconcile: Handoff carries last-synced: . A session that

starts (magic phrase, or any repo containing Handoff.MD) must read it fully, then FIRST run git log --oneline ..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):

## Power Coding (auto — do not remove without asking the user)
At session start read Handoff.MD; FIRST run `git log --oneline ..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  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 /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 "); 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 → ) 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.

1. 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: header — this is what makes staleness mechan

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: APareek89
• Source: APareek89/power-coding
• License: MIT

Install and usage instructions live in the source repository linked above.