agentleFS
os-factoryos-factory/har/.claude/skills/v1-milestone/SKILL.md

v1-milestone

Skill133 starsChanged 3 months agoApache-2.0View on GitHub

Factory line for executing one milestone of the HAR v1.0.0 refactor (epic os-factory/har#225) — plan the wave of parallel subagents, implement each issue in its own HAR slot, ship stacked PRs, run the fixture-e2e milestone gate, and hand off for review. Use when asked to "run the next v1 milestone", "work on v1.0.0", "execute M0/M1/…", or "run the milestone gate".

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

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

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

    Integration branch: all v1 work lands on the long-lived v1 branch, never directly on main.

    line 43
  2. Very specific:

    After Antoine merges the bottom PR into v1: retarget the next PR to v1 (gh pr edit --base v1) and rebase the remainder (git rebase --onto …

    line 92
  3. Very specific:

    Keep v1 current: after upstream main moves (0.x patches), merge main into v1 before starting the next milestone.

    line 95
  4. Distinctive:

    Never print a repo's remote URL (git remote -v) in logs — remotes can embed credentials.

    line 133
  5. Very specific:

    All the usual dogfood rules from .har/README.md apply.

    line 136

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

HAR v1.0.0 milestone factory line

Instance of the factory-line template. Program data: v1-milestone.line.json. This skill stays the executable playbook for the 1.0.0 run. Stacked PRs, GitHub-issue stations, and the car-app jig are this line's tactics — not the primitive. To run a different program, copy a line file, not this skill.

Execute one milestone of the v1.0.0 refactor end-to-end: sync → wave plan → parallel implementation → stacked PRs → gate → handoff.

Source of truth is GitHub: epic #225 and its sub-issues #226–#243 (plus triaged bugs #195–#198). Never duplicate the plan into files; report progress as issue comments and epic checkboxes.

Input: a milestone id M0..M5 (default: the first milestone whose issues are not all closed).

Milestone map

MilestoneIssuesWaves (each {} group = one subagent; groups in a wave run in parallel)
M0 Foundations + 0.x patches#226 #227 #228 #229 #196 #197 #198 + #195 (skip-ci half only)Wave 1: {#228} {#196} {#197} {#198} {#195} · Wave 2: {#226} · Wave 3: {#227} {#229}
M1 Contract#230 #231 #232 #233Wave 1: {#230} {#233} · Wave 2: {#231} · Wave 3: {#232}
M2 Runtime into package#234 #235 #236Wave 1: {#234} split into parallel forks per module (ports/preflight, worktree+launch, provisioning, infra, slot-registry) + one integration fork · Wave 2: {#235} {#236}
M3 Adaptation & extensibility#237 #238 #239 #240Wave 1: all four in parallel · Wave 2: integration pass
M4 Migration & docs#241 #243Wave 1: both in parallel
M5 Release gate#242 + the v1 → main release PRSequential; ends in handoff for the 1.0.0 release decision

Waves are ordered by real file conflicts: #226 rewrites the template tree, so #227/#229 (and anything touching src/templates/) must stack on top of it; #231 needs #230's env schema; #232 validates both.

Phase 0 — Sync

  1. gh issue view 225 + gh issue list --milestone 1.0.0 --state all — determine milestone state; confirm (or take as argument) which milestone to run.
  2. Integration branch: all v1 work lands on the long-lived v1 branch, never directly on main. Assert the main checkout is on v1, clean, and up to date (create it from main if it does not exist yet: git checkout -b v1) — har env launch bases every session worktree on the main checkout's current HEAD, so this is what makes every slot build on v1.
  3. Preconditions: npm run build succeeds; Docker running only if Mission Control (har control up) is wanted — the fixture itself is SQLite and needs no Docker.
  4. Re-read each issue in the milestone: bodies carry file:line references, task checklists, and acceptance criteria from the architecture audit.

Phase 1 — Wave plan

Print the wave plan for the chosen milestone (from the map above, adjusted for issues already closed). For each group note: issue, branch name (v1/<issue#>-<slug>), stack position, HAR slot to use (1–5, one per concurrently running subagent, checked free via har env status).

Phase 2 — Execute waves

For each wave, spawn one fork subagent per group, in parallel (single message, multiple Agent calls, subagent_type: "fork"). Each fork:

  1. Launches its assigned slot from the milestone stack base: har env launch <slot> --work-id <issue#> --work-source github --work-url <issue url>. Occupied slot → complete/teardown first (never share slots between forks).
  2. Edits only in the returned work dir; follows the issue's task checklist and acceptance criteria.
  3. Conventional commits referencing the issue (fix: … (#196), feat!: … (#234)). Breaking-change commits are fine on v1 — semantic-release only runs on main (release.config.cjs), so 1.0.0 is cut exactly once, by the final v1 → main merge in M5.
  4. Runs full verify in-slot until green; extends .har/stages/fixture-e2e.sh's milestone_asserts case when the issue makes a pending assert implementable (e.g. #232 → M1 doctor checks, #235 → M2 shim parity, #241 → M4 migration).
  5. Reports back: branch, commits, verify result, deviations. Forks never push, PR, complete, or teardown on their own.

The orchestrator reviews each fork's branch, resolves cross-branch conflicts itself, and rebases branches into the milestone stack order.

Phase 3 — Stacked PRs

  • One branch/PR per issue. Bottom PR bases on v1 (never main); every other PR bases on its predecessor: gh pr create --base <prev-branch> --head <branch>.
  • PR body: Closes #<issue>, stack position (Stack 2/4 — based on #<prev PR>), gate status, and the standard footer: 🤖 Generated with [Claude Code](https://claude.com/claude-code).
  • After Antoine merges the bottom PR into v1: retarget the next PR to v1 (gh pr edit --base v1) and rebase the remainder (git rebase --onto v1 <old-base> <branch>).
  • Keep v1 current: after upstream main moves (0.x patches), merge main into v1 before starting the next milestone.

Phase 4 — Milestone gate

From the top of the stack (a slot launched off it):

npm run build && npm test
HAR_FIXTURE_E2E=1 HAR_FIXTURE_MILESTONE=<M#> har env verify <slot> --full

Full verify runs typecheck/build/docs/tests/lint/docs-drift plus fixture-e2e, which clones /home/antoine/Documents/osfactory/examples/car-app into ~/.har-fixtures/ and drives the freshly built CLI through maintain → launch → full verify (incl. Playwright) → status → complete on the adapted harness, plus a fresh env init lifecycle, plus the milestone's asserts. Because it runs through har env verify, the gate is recorded in .har/runs/ and visible in Mission Control (har control up if not running).

Red gate → fix in-stack, re-run. Never hand off a red gate. Never bypass (HAR_SKIP_GATE, --no-verify).

Phase 5 — Handoff (required)

Post a milestone summary comment on #225: PRs in stack order, gate run id + result, fixture evidence (from .har/artifacts/fixture-e2e/), deviations. Then stop and wait for Antoine's review — never merge, push to main, or release autonomously. 1.0.0 is cut only by the final M5 v1 → main release PR he approves — merged as a merge commit (not squash) so semantic-release reads the individual feat!:/feat:/fix: commits; if squashed instead, the squash message must carry the BREAKING CHANGE: footer.

Safety rails

  • The fixture source repo is never modified — clones only (~/.har-fixtures/car-app*), remotes scrubbed to invalid://scrubbed.
  • Never print a repo's remote URL (git remote -v) in logs — remotes can embed credentials.
  • One HAR slot per concurrent fork; occupied slots always block.
  • All the usual dogfood rules from .har/README.md apply.

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.