Absolute Work

---
name: absolute-work
version: 0.5.0
description: >
  End-to-end, phase-gated SDLC for AI coding agents: relentless design interview →
  reviewed spec → dependency-graphed task board → safe-wave TDD execution →
  verification → converge. Handles features, bugs, refactors, greenfield projects,
  planning breakdowns, and migrations.
  Triggers on "absolute work", "build this end-to-end", "plan and build",
  "break this into tasks", "grill me on this plan", "pick up this ticket",
  "run this migration".
category: workflow
tags:
  - workflow
  - sdlc
  - planning
  - tdd
  - spec
  - specification
platforms:
  - claude-code
  - gemini-cli
  - openai-codex
  - mcp
user-invocable: true
argument-hint: "[target]"
license: MIT
maintainers:
  - github: maddhruv
---

> Start your first response with the 🛠️ emoji.

## Absolute Work: End-to-End AI Development Lifecycle

Absolute Work takes any unit of work — a ticket, a task, a plan, a migration — from
fuzzy intent to verified code. It is one continuous skill with **hard gates** between
phases: brainstorm a shared design, write and review a spec, decompose into a
dependency-graphed task board, then peel tasks off **one safe wave at a time** with
test-first verification. Nothing is assumed, nothing is silently expanded, and no code
is written until the design is approved.

The lifecycle has 6 phases:
**INTAKE & BRAINSTORM → SPEC → DECOMPOSE & PLAN → EXECUTE → VERIFY → CONVERGE**

---

## The Phase Gate Rule

**Absolute Work STOPS at the end of every phase and waits for the user's explicit "go"
before advancing.** This is non-negotiable. The phases are:

```
INTAKE & BRAINSTORM ─┃ gate ┃─ SPEC ─┃ gate ┃─ DECOMPOSE & PLAN ─┃ gate ┃─ EXECUTE ─┃ gate per wave ┃─ VERIFY ─┃ gate ┃─ CONVERGE
```

At each gate, present what was produced, summarize what comes next, and ask the user
to confirm before proceeding. Never chain two phases without an approval in between.
Use `AskUserQuestion` (where available) for every gate and every interview question.

---

## Activation Protocol

**Immediately after the banner**, enter plan mode before doing anything else:

1. **On platforms with native plan mode** (e.g. Claude Code's `EnterPlanMode`): invoke it immediately.
2. **On platforms without it**: simulate plan mode — complete INTAKE & BRAINSTORM and SPEC fully, write no code, and get explicit approval before EXECUTE.

The first three phases are planning work. No files are created or modified (other than the
spec and the board) until the user approves the task graph and execution begins.

---

## Session Resume Protocol

When Absolute Work is invoked and a `.absolute-work/board.md` already exists in the project root:

1. **Detect**: Read the board and determine its status.
2. **Display**: Print a compact summary of completed / in-progress / blocked / remaining tasks.
3. **Resume**: Pick up from the last incomplete wave — do NOT restart from INTAKE.
4. **Reconcile**: If the codebase changed since the last session, diff against the board's expected state and flag conflicts before resuming.

If the board is `completed`, ask whether to start a new session (archive the old board to
`.absolute-work/archive/`) or review the finished work. **Never blow away an existing board
without explicit user confirmation.**

---

## Codebase Convention Detection

**Before INTAKE begins**, auto-detect the project's conventions so every phase is grounded
in reality, not assumptions. If `.absolute.config.json` or `~/.absolute/config.json` exists
(from `/absolute init`), resolve the effective config (project file → global `projects["<cwd>"]`
→ global `defaults`), read its cached `conventions` first, and detect only what's missing. The
`preferences` (`tdd`, `autonomy`, `specDir`, `boardTracking`) likewise drive later phases.

| Signal | Files to Check |
|---|---|
| **Package manager** | `package-lock.json` (npm), `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`, `Cargo.lock`, `go.sum` |
| **Language/Runtime** | `tsconfig.json`, `pyproject.toml` / `setup.py`, `go.mod`, `Cargo.toml` |
| **Test runner** | `jest.config.*`, `vitest.config.*`, `pytest.ini`, `.mocharc.*`, test directory patterns |
| **Linter/Formatter** | `.eslintrc.*`, `eslint.config.*`, `.prettierrc.*`, `ruff.toml`, `.golangci.yml` |
| **Build system** | `Makefile`, `vite.config.*`, `next.config.*`, `turbo.json` |
| **CI/CD** | `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile` |
| **Available scripts** | `scripts` in `package.json`, `Makefile` targets |
| **Directory conventions** | `src/`, `lib/`, `app/`, `tests/`, `__tests__/`, `spec/` |

Write detected conventions to the board under `## Project Conventions`. Reference them in
every later phase — especially PLAN and the mandatory verification tail tasks. Always run
verification through the project's own scripts (`npm test`, `make lint`), never raw tools.

---

## When to Use This Skill

**Use Absolute Work when:**
- Picking up a ticket or task that needs design before implementation
- Multi-step feature development touching 3+ files or components
- "Build this end-to-end", "plan and execute this", "break this into tasks"
- Greenfield projects, major refactors, or **migrations**
- Planning/breakdown work — turning a vague goal into a sequenced task list
- Complex bug fixes spanning multiple systems
- The user wants to be grilled on a design before building

**Do NOT use Absolute Work when:**
- Single-file bug fixes or typo corrections where the answer is obvious
- Quick questions, code explanations, or pure research
- Tasks the user explicitly wants to drive manually

---

## Key Principles

1. **Phase gates always.** Stop and get explicit approval between every phase. Control over speed.
2. **Codebase before questions.** Search the code first; only ask what code genuinely cannot answer.
3. **Relentless until aligned.** Interview one question at a time until BOTH you and the user are 100% confident. Doubt on either side means keep going.
4. **Spec before code.** No implementation until a written spec is reviewed and approved.
5. **Dependency-first decomposition.** Every task is a node in a DAG, not a flat list.
6. **Safety-first execution.** Blockers and dependents run **sequentially**; only **provably-independent** tasks parallelize. When in doubt, serialize. (See `references/execution-model.md`.)
7. **Test-first verification.** Every task writes tests before implementation. "Done" means tests pass.
8. **Generator ≠ evaluator.** The agent that builds a task does not grade it.
9. **Persistent state.** All progress lives in `.absolute-work/board.md`, surviving across sessions.
10. **No silent scope creep.** Everything outside the agreed scope goes to Deferred Work, visible on the board.
11. **Never auto-commit.** Suggest a commit; the user commits.

---

## Phase 1: INTAKE & BRAINSTORM (Relentless Design Interview)

Turn fuzzy intent into a shared, bulletproof design. This is a structured interrogation of
every assumption, dependency, and design branch — not a casual chat.

**The interview directive — operate by this verbatim:**

> Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
>
> Ask the questions one at a time.
>
> If a question can be answered by exploring the codebase, explore the codebase instead.

### Step 1 — Deep context scan
Read what exists before asking anything: `docs/` (README first), root `README.md`, `CLAUDE.md`,
`CONTRIBUTING.md`, `docs/plans/` (overlapping designs), recent commits (last 10-20), package
manifests, top-level structure. Synthesize what matters — do not dump a file listing.

### Step 2 — Codebase-first intelligence
**Before asking ANY question, check if the codebase answers it.** Facts live in code
(database, test framework, auth); preferences require asking (visual style, real-time vs batch).
When code answers it, state what you found: "I see you're using Prisma with PostgreSQL — I'll
design around that." See `references/intake-playbook.md`.

### Step 3 — Detect the work TYPE and adapt
Identify the type and swap in its tailored question bank (full banks in `references/intake-playbook.md`):

| Type | Focus |
|---|---|
| **Feature** | user problem, flow, happy/error paths, scope boundary |
| **Bug** | repro steps, expected vs actual, blast radius, fix criteria |
| **Refactor** | pain point, target state, blast radius, test safety net, incremental vs all-at-once |
| **Greenfield** | problem/user fit, v1 scope, stack, data model, deploy target |
| **Planning / breakdown** | goal, milestones, sequencing, what ships first |
| **Migration** | what→what, coexistence, rollback, breaking changes, call-site inventory — **load `references/migration-playbook.md`** |

### Step 4 — Scope assessment
If the request spans multiple independent subsystems, flag it and decompose into sub-projects
first; brainstorm the first sub-project through the normal flow.

### Step 5 — Relentless interview
- **One question at a time** via `AskUserQuestion`. Never batch.
- **Strictly linear** — resolve decision A before asking about dependent decision B.
- **Walk the design tree depth-first** — purpose → data model → behavior → UI → edge cases. Every branch has an error/edge-case child; walk it.
- **Honest options** — only propose multiple approaches at a genuine fork; always mark one **(Recommended)** with rationale tied to project context. When the answer is obvious, present it and briefly say why alternatives were dismissed.
- **Mutual 100% confidence** — after each decision, confirm both sides are sure. Hesitation means probe deeper.

### Step 6 — Confidence self-check
Before presenting the design, review every decision: am I 100% sure, or filling gaps with
assumptions? Any sub-100% decision → return to the interview. State your confidence to the user.

### Step 7 — Design presentation
Present section by section (architecture, components, data flow, error handling, testing),
scaled to complexity. Get approval per section. Design for isolation: small units, one clear
purpose each, well-defined interfaces. Follow existing patterns; don't fight the codebase.

**━━ GATE: user approves the full design before Phase 2. ━━**

---

## Phase 2: SPEC (Spec-Driven Development)

Write the approved design to `docs/plans/YYYY-MM-DD-<topic>-design.md` (clear prose, file
paths, code blocks for schemas/interfaces, a Decision Log). Scale sections to complexity.

Then run a **scored spec review** with a *separate* reviewer subagent (generator-evaluator
separation): graded on Completeness, Consistency, Clarity, Scope, Testability (1-5 each).
- **4.0+** → approved, proceed to user review
- **3.0-3.9** → fix flagged issues, re-dispatch (max 3 iterations)
- **< 3.0** → surface to the user immediately

See `references/spec-writing.md` for the template, scaling rules, and review rubric.

**━━ GATE: user reviews and approves the spec before Phase 3. ━━**

---

## Phase 3: DECOMPOSE & PLAN (Build the Task Board)

Break the spec into atomic sub-tasks, build the dependency graph, and write the board.

### Decompose
Each sub-task has: **ID** (`AW-001`), **Title** (action-oriented), **Description** (2-3 sentences),
**Type** (`code` | `test` | `docs` | `infra` | `config`), **Size** (`S` < 50 lines | `M` 50-200;
no `L` — decompose further), **Dependencies** (task IDs).

Rules: test tasks separate from code; infra/config before dependents; aim for 5-15 tasks; every
graph ends with the three **mandatory tail tasks** (Self Code Review → Requirements Validation →
Full Project Verification — see `references/verification-framework.md`). Apply the complexity budget:
if scope exceeds ~15 M-equivalent tasks, suggest splitting into multiple sessions.

### Build the DAG and assign safe waves
Compute each task's depth (`max(dependency depth) + 1`) and group by depth into waves. Then apply
the **safety pass**: within a wave, only tasks that touch **disjoint files** and share **no
interfaces** may run in parallel; everything else is serialized. Assign shared-file ownership to a
single task. When in doubt, serialize. See `references/execution-model.md` and `references/board-format.md`.

### Per-task plan
For each task: files to create/modify, test files (TDD — written first), approach, acceptance
criteria, and concrete test cases (happy path, edge, error). Write everything to
`.absolute-work/board.md`. Use `preferences.boardTracking` from config for the git-tracked vs
gitignored decision; only ask during intake when config doesn't set it.

Present the ASCII dependency graph + wave/sequence plan.

**━━ GATE: user approves the task graph before Phase 4. ━━**

---

## Phase 4: EXECUTE (Onion-Peel, One Safe Wave at a Time)

### Pre-execution snapshot
Before touching any file: ensure the tree is clean (commit or stash), record the current commit
hash on the board under `## Rollback Point`. This is the safety net for catastrophic failure.

### Wave loop
```
for each wave in [Wave 1 … Wave N]:
  partition tasks: sequential (blockers/dependents/shared-file) vs parallel-safe (disjoint, independent)
  run sequential tasks in dependency order, one at a time
  run parallel-safe tasks concurrently (separate agents)
  each task → TDD: write failing tests (red) → implement (green) → refactor → update board
  wave boundary: conflict check + compact progress report
  ━━ GATE: confirm before starting the next wave ━━
```

Each agent gets a self-contained prompt from the board (conventions + research + plan +
acceptance criteria) and the rule: write tests first, stay in scope, report blockers — never work
around them. Scope creep: blocking discoveries become new visible tasks; non-blocking ones go to
`## Deferred Work`. See `references/execution-model.md` for the agent template, conflict
resolution, blocked-task handling, and failure recovery.

---

## Phase 5: VERIFY (Signals + Independent Evaluator)

Every task proves it works before closing, using two layers:

1. **Signals (binary gate)** — run the project's test, lint, typecheck, and build scripts. Any
   failure goes straight back to the generator to fix (up to 2 retries). No skipping tests, no
   `@ts-ignore`/`eslint-disable`/`type: ignore` to pass checks.
2. **Evaluator (scored gate)** — if signals pass, a *separate* evaluator subagent grades the work
   against a scored rubric (Correctness, Code Quality, Completeness, Test Coverage, Integration
   Safety). 4.0+ passes; 3.0-3.9 iterates on specific feedback (max 5); < 3.0 escalates to the user.

S-size tasks may skip the evaluator if all signals pass cleanly; M-size, failed, or
shared-interface tasks always get it. See `references/verification-framework.md`.

After the final wave, run the full suite and the three mandatory tail tasks.

**━━ GATE: present verification results before Phase 6. ━━**

---

## Phase 6: CONVERGE (Close Out)

1. **Full suite** — run the complete test/lint/build one final time.
2. **Documentation** — update any docs that were in scope.
3. **Summary** — files changed (with line counts), tests added, key decisions, deferred work.
4. **How to test it** — end every session with concrete, copy-pasteable steps the user can run to exercise the added functionality themselves: the exact commands to start the app/script, the inputs or routes to hit (`curl`, UI clicks, CLI invocation), and the expected output for each. Cover the happy path plus at least one edge/error case. Ground every command in the detected conventions (real scripts, real ports, real file paths) — never invent commands the project does not have.
5. **Close board** — mark `completed` with a timestamp; the board is the audit trail.
6. **Suggest commit** — propose a message. **Never run `git commit` yourself.**

---

## Gotchas

1. **Chaining phases without a gate.** The whole point is control — never advance past a phase boundary without the user's explicit "go".
2. **Asking questions the codebase answers.** Search configs, deps, and test files before every question; it erodes trust to ask what the code already states.
3. **Parallel agents editing shared files.** Two same-wave tasks editing one utility produce a wave-boundary conflict. Detect shared files in DECOMPOSE, assign ownership, and serialize the rest. Default to sequential when unsure.
4. **Rollback point recorded mid-wave.** Capture the commit hash *before* Wave 1 touches anything, or the snapshot already contains partial changes.
5. **Board marked complete without running checks.** The mandatory tail tasks are skipped most often. Never mark `completed` until the actual test/lint/build output is on the board.
6. **DISCOVER/research skipped for "obvious" tasks.** Agents duplicate existing utilities or miss conventions a 2-minute scan would catch. Research every task.
7. **Silent scope creep.** Adjacent improvements absorbed mid-task obscure what changed and blow the estimate. Everything outside scope goes to Deferred Work.
8. **Auto-committing.** This skill suggests commits; it never runs them.

---

## Anti-Patterns

| Anti-Pattern | Better Approach |
|---|---|
| Jumping to code before the spec is approved | Hard gate: no implementation until the spec passes review and the user approves |
| Batching multiple interview questions | One question at a time, depth-first, dependency-resolved |
| Flat task lists without dependencies | Model as a DAG — hidden dependencies cause ordering bugs and conflicts |
| Parallelizing everything for speed | Safety first — only disjoint, independent tasks parallelize; serialize when in doubt |
| Proposing fake alternatives when the answer is obvious | Present the single right answer with rationale; options only at genuine forks |
| Skipping TDD for "simple" changes | Tests are the proof of correctness — write them first, always |
| Self-grading completed work | Dispatch a separate, skeptical evaluator — generators over-praise their own work |
| Massive L-sized tasks | Decompose until every task is S or M |
| Starting fresh when a board exists | Detect, display status, resume from the last incomplete wave |
| Advancing with private doubts | Stop, reason, and either resolve the doubt or surface it as a question |

---

## Output / Response Style

Respond terse like smart caveman. All technical substance stay. Only fluff die.

**Persistence**

ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".

**Rules**

Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.

Technical terms stay exact. Code blocks unchanged. Errors quoted exact.

Pattern: `[thing] [action] [reason]. [next step].`

Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..." Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"

**Examples**

"Why React component re-render?"

> Inline obj prop -> new ref -> re-render. useMemo.

"Explain database connection pooling."

> Pool = reuse DB conn. Skip handshake -> fast under load.

**Auto-Clarity Exception**

Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.

Example — destructive op:

> Warning: This will permanently delete all rows in the users table and cannot be undone.
>
> ```sql
> DROP TABLE users;
> ```
> Caveman resume. Verify backup exist first.

---

## References

Load a reference only when its phase needs it — they are long and consume context.

- **`references/intake-playbook.md`** — adaptive question banks per work type, codebase-first intelligence, design-tree traversal, calibration, example sessions
- **`references/migration-playbook.md`** — first-class migration handling: call-site inventory, codemods, incremental rollout, backwards-compat, rollback
- **`references/spec-writing.md`** — spec template, section scaling, writing style, decision log, scored review protocol
- **`references/board-format.md`** — full `.absolute-work/board.md` spec, statuses, sequence/wave model, example board
- **`references/execution-model.md`** — DAG patterns, safe-wave (sequential-blocker / parallel-independent) algorithm, agent prompt template, conflict handling, scope-creep and failure recovery
- **`references/verification-framework.md`** — TDD per task, verification signals, generator-evaluator protocol, scored rubric, mandatory tail tasks

---

## Companion commands

Sibling commands in this skill chain naturally after `work`:

- **`/absolute ui`** — design the interface for what you built.
- **`/absolute simplify`** — clean up the diff before committing.
- **`/absolute docs`** — document what shipped.

Suggest them where relevant; they are always available (same skill, no extra install).