agentleFS
ridwankustantoridwankustanto/mandor/.claude/skills/pm-build/SKILL.md

pm-build

Skill2 starsChanged 41 days agoMITView on GitHub

Phase 5, Build. Break approved stories into tasks and sub-tasks, implement them, and let the git hook keep the tree honest. Use after /pm-design, when the user says "/pm-build", "start implementing", "break this into tasks", "what should I work on", or asks to build an approved story.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 5 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run ./pm q "SELECT code_path FROM project".

    line 10
  2. Distinctive:

    This repo: commit code here directly.

    line 18
  3. Distinctive:

    Never scaffold a stack the user has not chosen.

    line 20
  4. Distinctive:

    Full mode: only epics that passed their design gate.

    line 32
  5. Very specific:

    Check the standards first: Read standards/guardrails.md and point-of-view.md.

    line 42
  6. Distinctive:

    Interfaces: Every endpoint, message, command or UI to backend contract this epic adds, agreed now.

    line 47
  7. Distinctive:

    Every screen state from the inventory is covered by a task or explicitly deferred.

    line 82
  8. Very specific:

    Every other story in an active milestone gets at least one task.

    line 87
  9. Very specific:

    Put the code in the message and the post-commit hook does the rest: it stamps the sha and moves the item to review.

    line 114
  10. Very specific:

    If implementation reveals the story is wrong, that is a change, not a detour.

    line 156

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/pm-build: tasks that stay true without anyone maintaining them

0. Where the code lives

Run ./pm q "SELECT code_path FROM project". If it is empty, ask with a form:

  • Nested code/ (recommended): its own git repo inside this folder, ignored by this repo. git init code (or clone an existing repo into code/), init the stack there, then ./pm link code. That installs the commit hook, writes a block into its CLAUDE.md, gives it the session briefing and adds /code/ to .gitignore.
  • Elsewhere: an existing repo that must stay where it is. ./pm link <path>, same result with absolute paths.
  • This repo: commit code here directly. Fine for something tiny that will never split.

Never scaffold a stack the user has not chosen.

The code repo imports standards/tokens.css, copied or referenced by path, whichever the stack prefers. Tokens never get retyped by hand.

1. Plan the epic before any task starts

Lite mode has no spec phase, so there is no tree yet. Make a thin one now: one milestone, one epic per thing the user will notice, two to five stories under each. Five minutes, not a phase. The edit pass needs epics to walk through. Lite skips the plan gate below, but still fills the data model and interfaces before writing code.

Full mode: only epics that passed their design gate. Check first:

./pm tree
./pm gate list

The spec said what and why. The plan says how, once per epic, before code. It lands in the epic's area TRD, docs/engineering/trd/<area>.md, not in a new document.

  1. Check the standards first. Read standards/guardrails.md and point-of-view.md. Name any part of this epic that would break one, and either change the approach or write down why the exception is worth it.
  2. Data model from the stories. Entities, fields, validation rules and state changes, each row naming the story that needs it. A table no story asks for does not get built.
  3. Interfaces. Every endpoint, message, command or UI to backend contract this epic adds, agreed now. With both sides fixed, tasks on either side can run at once.
  4. Unknowns become ADRs. Anything the plan cannot decide yet (a library, a limit, a storage choice) is researched now and written as an ADR, decision, why and alternatives, before code depends on it.
  5. Prove it end to end. Fill that section of the epic doc: setup, the command or user action, what you should see. /pm-edit and /pm-ship run these steps.
  6. Check the standards again against the finished plan. Designing the data model is where shortcuts sneak in.

Show the plan, then:

./pm gate open plan EPIC001
./pm gate approve plan --subject EPIC001 "<the one decision that shapes it>"

./pm check fails while any task under an epic is in progress without an approved plan.

2. Break stories into tasks

Then break each story down. A task is a unit of build work under exactly one story.

./pm task title="<verb first, one outcome>" parent=STORY001 type=impl owner=agent
./pm sub  title="<a slice of that task>" parent=TASK004
./pm set TASK004 blocked_by=TASK002

Types: design, impl, test, infra, docs, fix.

Rules for a good breakdown:

  • One outcome per task. If the title needs "and", it is two tasks.
  • Sub-tasks only when a task genuinely splits. Do not manufacture a third level.
  • Every screen state from the inventory is covered by a task or explicitly deferred. Empty, loading and error states are tasks, not afterthoughts.
  • Infra and test tasks exist from the start. They are not a phase at the end.
  • blocked_by gets filled when it is real, so the board can show the critical path.
  • A constraint story with priority=wont gets no tasks. It is a non-goal.
  • Every other story in an active milestone gets at least one task. ./pm check names the ones nothing builds.

3. Work

./pm set TASK004 status=in_progress
./pm context TASK004

./pm context prints the point of view, the chain from this task up to its epic, the screens and their states, and the guardrails. Build from that, every task, even the small ones. It is how standards reach the code at the moment they matter instead of being a document the agent may or may not have read.

Then implement, in the code repo.

Climb the ladder, stopping at the first rung that holds: does this need to exist, does the codebase already have it, does the stdlib or the platform cover it, is it one line, only then write it. Reuse components from the design system and layouts from standards/patterns/. Never build a second Button. Every color, size and radius comes from tokens.css.

Non-trivial logic leaves one runnable check behind. Not a suite, one check that fails if the logic breaks.

4. Commit with the work item code

Put the code in the message and the post-commit hook does the rest: it stamps the sha and moves the item to review.

feat: render the inbox empty state TASK004

That replaces "remember to update the board". Instructions get skipped, hooks do not.

5. Close upward, never downward

A parent cannot be closed while a child is open. ./pm check fails on it, and that is deliberate: it is the most common way a board starts lying.

./pm set SUB001 status=done
./pm set TASK004 status=done
./pm set STORY001 status=done      # only once every task under it is settled

done means built. verified is a separate claim, it belongs to /pm-ship, and it needs a passing test run naming the story. Do not skip ahead to it, ./pm check will catch it.

6. Decisions made while building

Implementation forces choices that design never surfaced. When one is load bearing, write an ADR at the moment it is made, not at the end of the week:

./pm add adr title="<decision>" status=accepted decision="<what>" \
  why="<what forced it>" alternatives="<rejected, and why>" \
  doc_path=docs/engineering/adr/NNNN-<slug>.md

Also update the relevant docs/engineering/trd/<area>.md. One area file per subsystem, so this stays a small edit rather than a rewrite of one enormous document.

Deliberate shortcuts get a ponytail: comment (or whatever tag your team greps for) naming the ceiling and the upgrade path, and a line in the area TRD's deferred section.

Ask when the build contradicts the spec

If implementation reveals the story is wrong, that is a change, not a detour. Say so and run /pm-change. Do not quietly build the thing you think is better.

Close the milestone

Built is not done. Closing here moves the project to /pm-edit, not to ship.

./pm check
./pm gate open build M0
./pm gate approve build --subject M0 "M0 tasks done and reviewed"
./pm set M0 status=done
./pm gate approve build "M0 built"
./pm phase next                      # lands on edit

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.