skills · Open source · Agent skills

From intent to signoff, one stage at a time.

Agent skills for Claude Code, Codex, and other skill-aware agents. The main piece is tk workflow: a staged, document-driven way to take one change from intent to signoff. It runs with one agent, and other agents join for review and debate when you ask.

$npx skills add tkhwang/skills -g

GitHub →

Claude Code · Codex · Grok · any skill-aware agent

tk workflow: five stages (intent, plan, implement, verify, signoff) run left to right with a human approval gate between each, in three parts: you lead and AI sharpens (intent, plan), hand off (implement), check together (verify, signoff). tk-check runs the repo's typecheck, lint, format, tests and build for implement and verify. Intents are permanent, tasks are per piece of work, specs describe current behaviour. — Five stages run left to right with a human approval gate between each, in three parts: you lead and AI sharpens (intent, plan), hand off (implement), check together (verify, signoff). tk-check runs the repo's checks for implement and verify. Intents are permanent, tasks are per piece of work, specs describe current behaviour.

github stars: 0
skills: 11
stages · intent → signoff: 5
peer agents · claude · codex · grok: 3

What it is

Five stages. Files are the state.

Each stage reads a document and writes a document. Where work stands is derived from docs/, never from conversation memory, so any session can pick it up.

01
Files are the state
Intents are permanent, one per change. plan.md and todo.md live only for the current piece of work and are emptied at signoff. Specs describe how each module behaves now, in timeless language.
- docs/intents/<MODULE><NNN>-<slug>.md holds why, what, non-goals, R-numbered requirements, and the outcome
- docs/tasks/ holds the plan, the todo list, and each peer's reviews and debates
- tk-setup explores the repo once and writes docs/agents/tk-workflow.md
docs/ · files are the state any session resumes
```
docs/
├─ intents/AGENT001-tenant-export.md   permanent
├─ tasks/plan.md                         current work
├─ tasks/todo.md                         current work
├─ tasks/reviews/  ·  debates/           current work
├─ specs/export/                        permanent
└─ agents/tk-workflow.md                per repo
```
02
A human gate at every stage
A stage saves its artifact, prints a summary, and ends the turn. The next stage starts only on an explicit next. Hedged answers are not approval; the driver asks again.
- tk-intent interviews you against the code and numbers requirements R1, R2, …
- tk-plan turns the intent into vertical slices, each Backend → Frontend, with an R-id coverage matrix
- tk-implement checks boxes with evidence and runs a tk-check checkpoint after every sub-phase, fixing what fails
/tk-workflow waiting on you
1. [0]
  tk-intent
  R1 … Rn
  →
2. [1]
  tk-plan
  slices · coverage
  →
3. [2]
  tk-implement
  backend → frontend
  →
4. [3]
  tk-verify
  audit · R-ids
  →
5. [4]
  tk-signoff
  go / no-go
```
agent › plan.md saved · 3 slices · 0 open decisions. Turn ended.
you   › looks fine
agent › That is not an approval. Reply next or revise: …
```
03
Multi-agent review and debate
Say review or debate and other agents (claude, codex, grok) read the artifact or argue one open decision. They run headless, read-only, one process each. Their answers land in files, and one agent still does all the editing.
- tk-multi-review triages findings into patches, tk-grill questions, or deferred notes
- tk-multi-debate runs two written rounds, then the human decides through tk-grill
- Inside herdr the peers run in a sibling pane so you can watch; outside, they run directly
04
The agent never commits
It reads git, it does not write it. Commits, pushes, and branches are yours. tk-check runs typecheck, lint with warnings failing, format check, and tests at every checkpoint, and fixes what fails without silencing the tools. Before signoff, tk-verify runs them again with the plan's behaviour checks and audits the work.
- tk-signoff traces every R-id through plan, diff, and verification, then decides Go or No-Go
- On Go it appends the intent Outcome, updates module specs, and empties docs/tasks/
- Git history is the archive
/tk-signoff go
```
› /tk-signoff
R1 … R6 traced through plan · diff · verification
Go
+ intent Outcome appended
+ docs/specs/export/ updated
− docs/tasks/ emptied

$ git commit -m "feat(export): tenant CSV export"
  yours — the agent reads git, it never writes it
```

Skills

One hub, five stages, one interviewer, one checker, and two multi-agent helpers.

Workflow

The staged flow, driven by tk-workflow.

$ tk-setupOnce per repo. Writes docs/agents/tk-workflow.md: layout, docs paths, module codes, verify commands, peers.
$ tk-workflowHub. Derives the current stage from the files and routes to the next skill.
$ tk-intent [0]Reads your intent draft against the code, asks the important gaps, numbers requirements.
$ tk-plan [1]plan.md + todo.md: vertical slices, R-id coverage, no open decisions.
$ tk-implement [2]Works todo.md in order with evidence and a tk-check checkpoint at every sub-phase; runs to the end (all) or stops per slice.
$ tk-verify [3]tk-check in report mode plus behaviour checks, then an audit of tasks, R-ids, and tests, recorded per R-id.
$ tk-signoff [4]Traces every R-id. Go: outcome appended, specs updated, tasks emptied.

Multi-agent

Other agents join as read-only peers. The orchestrator stays the one agent that edits.

$ tk-multi-reviewclaude, codex, and grok review the artifact awaiting approval, each in its own process.
$ tk-multi-debatePeers argue one open decision in two written rounds; the human decides through tk-grill.
$ claude -p · codex exec -s read-only · grok -pHow peers run: headless, read-only, a self-contained prompt file in, an answer file out.

Which agents take part is a Peers table that tk-setup writes from what is installed.

Driver words

After the first stage command in a session, plain words keep the flow moving.

$ nextApprove the current artifact and start the next stage.
$ revise: …Send the artifact back with a change request.
$ slice · allLet tk-implement stop per slice, or run to the end.
$ checkRun tk-check on the current change and fix what fails.
$ review · debateBring in the peer agents at this gate.
$ status · stopShow where the work stands, or end the flow.

Other

Pieces that work on their own.

$ tk-grillAsks the unresolved decisions in a document one at a time, with a recommendation, and patches the answers in.
$ tk-checkRuns the repo's typecheck, lint, format check, tests, and build on the change, and fixes what fails, never with eslint-disable, @ts-ignore, or skipped tests.
$ npx skills updateUpdate installed skills later.
$ ./link.shDevelop: symlink the cloned repo into ~/.agents, ~/.claude, and ~/.codex skills.

install

Install

User-level, for every supported agent. Then run /tk-setup in a project, write your first intent, and run /tk-intent.

Every skill in the repo, user-level

$npx skills add tkhwang/skills -g

Let the files hold the state

Write the intent, approve each stage, and keep commits in your own hands. Review and debate are one word away when you want a second opinion.

Get started View on GitHub ↗

From intent to signoff, one stage at a time.

Five stages. Files are the state.

Files are the state

A human gate at every stage

Multi-agent review and debate