feat(agents): make Plane the first-level record for project work #26

Merged

john merged 1 commit from fm/fm-plane-first-habit into main 2026-09-03 23:51:56 +00:00

Conversation 0 Commits 1 Files changed 4 +140

john commented 2026-09-03 23:24:44 +00:00

Owner

Copy link

Summary

• Add an always-loaded "Plane: the first-level record" contract to AGENTS.md section 7, requiring every Plane story to be resolved or created at intake and updated (state + comment) at dispatch, blocked, PR opened, checks complete, and done-with-merge-commit, so the captain can reconstruct any work item's full state and history from Plane alone.
• Push the mechanics (story resolution and ownership verification, Plane state-name resolution, comment shape, and the real-vs-escaped-HTML rule) into a new agent-only skill, .agents/skills/plane-first-record/SKILL.md, classified agent-runtime in docs/documentation-audiences.json.
• Add tests/fm-plane-first-record.test.sh, a text-presence regression test pinning the contract wording in AGENTS.md and the skill's coverage of it, so the contract cannot be silently dropped or thinned later.

Placement

Placed as a subsection of section 7 (task lifecycle) rather than a new top-level section or an extension of section 6:

• Every named moment (intake, dispatch, blocked, PR opened, checks complete, done-with-merge-commit) is already a section 7 lifecycle event; putting the contract there keeps it beside the moments it governs.
• A new top-level section would force renumbering every one of sections 8-14 and every internal cross-reference to them, for no benefit.
• Section 6 owns durable-knowledge routing, not lifecycle-triggered actions; Plane updates are triggered by lifecycle events, so 7 fits the content better than 6.

On the new test (captain's ruling, recorded here for future readers)

no-mistakes's review step flagged the new test as ask-user: it is a pure source-content test (fixed-string greps against AGENTS.md/SKILL.md prose), normally an anti-pattern under the pipeline's test-quality rule, since a contract-preserving rephrase would break it and matching text alone doesn't prove behavior on its own. Escalated to the captain, who approved it as-is:

The reviewer's rule assumes an artifact with executable behaviour, and this one has none - the thing under test is instructional prose an agent reads, so text presence IS the property that matters, not a proxy for it. The brief asked for exactly this guard deliberately, and tests/fm-ask-user-authority.test.sh is established precedent for the same pattern in this repo. Narrowing the test to structural-only checks would trade away the only protection against a future silent thinning of the contract wording, which is precisely the risk this work was filed to prevent. The reviewer is right that a contract-preserving rephrase breaks the test; that is a maintenance cost rather than a defect, and arguably correct here - if someone rewords an always-loaded contract, a human should be made to look.

Verification

• bin/fm-doc-audience-check.sh - ok (surfaces=71 local_links=212)
• bin/fm-lint.sh (pinned ShellCheck 0.11.0) - clean
• no-mistakes pipeline (run 01M1MRJFTFX49X1FD07Y6RT5YS) - outcome passed: intent, rebase, review (one ask-user finding, captain-approved above), test, document, lint, and push all completed.
• The pipeline's pr/ci steps were skipped (skipping PR creation: provider unknown is not supported yet - this forge is not one the pipeline's PR automation recognizes), so this PR was opened directly against main.

## Summary - Add an always-loaded "Plane: the first-level record" contract to `AGENTS.md` section 7, requiring every Plane story to be resolved or created at intake and updated (state + comment) at dispatch, blocked, PR opened, checks complete, and done-with-merge-commit, so the captain can reconstruct any work item's full state and history from Plane alone. - Push the mechanics (story resolution and ownership verification, Plane state-name resolution, comment shape, and the real-vs-escaped-HTML rule) into a new agent-only skill, `.agents/skills/plane-first-record/SKILL.md`, classified `agent-runtime` in `docs/documentation-audiences.json`. - Add `tests/fm-plane-first-record.test.sh`, a text-presence regression test pinning the contract wording in `AGENTS.md` and the skill's coverage of it, so the contract cannot be silently dropped or thinned later. ## Placement Placed as a subsection of section 7 (task lifecycle) rather than a new top-level section or an extension of section 6: - Every named moment (intake, dispatch, blocked, PR opened, checks complete, done-with-merge-commit) is already a section 7 lifecycle event; putting the contract there keeps it beside the moments it governs. - A new top-level section would force renumbering every one of sections 8-14 and every internal cross-reference to them, for no benefit. - Section 6 owns durable-knowledge routing, not lifecycle-triggered actions; Plane updates are triggered by lifecycle events, so 7 fits the content better than 6. ## On the new test (captain's ruling, recorded here for future readers) `no-mistakes`'s review step flagged the new test as `ask-user`: it is a pure source-content test (fixed-string greps against `AGENTS.md`/`SKILL.md` prose), normally an anti-pattern under the pipeline's test-quality rule, since a contract-preserving rephrase would break it and matching text alone doesn't prove behavior on its own. Escalated to the captain, who approved it as-is: > The reviewer's rule assumes an artifact with executable behaviour, and this one has none - the thing under test is instructional prose an agent reads, so text presence IS the property that matters, not a proxy for it. The brief asked for exactly this guard deliberately, and `tests/fm-ask-user-authority.test.sh` is established precedent for the same pattern in this repo. Narrowing the test to structural-only checks would trade away the only protection against a future silent thinning of the contract wording, which is precisely the risk this work was filed to prevent. The reviewer is right that a contract-preserving rephrase breaks the test; that is a maintenance cost rather than a defect, and arguably correct here - if someone rewords an always-loaded contract, a human should be made to look. ## Verification - `bin/fm-doc-audience-check.sh` - ok (`surfaces=71 local_links=212`) - `bin/fm-lint.sh` (pinned ShellCheck 0.11.0) - clean - `no-mistakes` pipeline (run `01M1MRJFTFX49X1FD07Y6RT5YS`) - outcome `passed`: intent, rebase, review (one `ask-user` finding, captain-approved above), test, document, lint, and push all completed. - The pipeline's `pr`/`ci` steps were skipped (`skipping PR creation: provider unknown is not supported yet` - this forge is not one the pipeline's PR automation recognizes), so this PR was opened directly against `main`.

john added 1 commit 2026-09-03 23:24:44 +00:00

feat(agents): make Plane the first-level record for project work ... 27df6e570f

Add an always-loaded contract in AGENTS.md section 7 requiring every
Plane story to be resolved or created at intake, then updated with a
comment at dispatch, blocked, PR opened, checks complete, and
done-with-merge-commit, so the captain can reconstruct any work
item's state and history from Plane alone. Documents firstmate
produces get their substance as a story comment, not just a local
path; a repo with no Plane project (including this one) tracks on
PYR0D.

Mechanics that don't belong in the always-loaded budget - story
resolution and ownership verification, state names, comment shape,
and the real-vs-escaped-HTML failure mode - move to a new
plane-first-record skill. A regression test pins the contract text
and the skill's coverage of it.

john merged commit f16fb6471e into main 2026-09-03 23:51:56 +00:00

john referenced this pull request from a commit 2026-09-03 23:51:57 +00:00

feat(agents): make Plane the first-level record for project work (#26)

john referenced this pull request from a commit 2026-09-29 18:54:29 +00:00

feat(workflow): port the Plane record, imported skills, and the security playbook

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

john/firstmate!26

No description provided.