Skip to content

INSTRUCTIONS.md

Latest commit

 

History

History
158 lines (125 loc) · 12.1 KB

INSTRUCTIONS.md

File metadata and controls

158 lines (125 loc) · 12.1 KB

INSTRUCTIONS.md

Procedural instructions and workflow guidance for agents working with the Port repository.

The Turn Loop

Port uses Keel as its project management engine. Your job is to move the board through the canonical Orient -> Inspect -> Pull -> Ship -> Close loop while eliminating drift.

keel turn is the canonical reference surface for this rhythm. Every session follows this deterministic cycle:

  1. Orient: Run keel heartbeat, keel health --scene, keel flow --scene, and keel doctor. This tells you whether the board is energized, healthy, and structurally coherent.
  2. Inspect: Run keel mission next --status and keel pulse. If routing is unclear, inspect keel roles or keel next --role <role> --explain.
  3. Pull: Choose the correct lane and role (manager, operator, or a configured role family) and pull exactly ONE slice of work.
  4. Ship: Execute the move, record proof while the work is fresh, and land the relevant lifecycle transition (story submit, voyage plan, bearing lay, etc.).
  5. Close:
    • Record your move in the mission LOG.md.
    • Heartbeat Check: Use keel heartbeat if you need to inspect the current activity source or confirm the circuit is still energized before the commit boundary.
    • Commit: Execute git commit. The installed hooks automatically run just quality, just test, and append doctor --status to the commit message. Resolve any issues if the commit is rejected.
    • Meaning Of Close: A slice is not shipped until the relevant code, proof, and .keel lifecycle churn are committed. Runtime proof alone is not a completion boundary.
  6. Re-orient: After the commit lands, run keel doctor --status and keel flow --scene to see what the board needs next. This is the "plug the cord back in" moment. If the delivery lane has ready work, start the next turn immediately. Only stop to ask the human when you reach a manual lane (design direction, bearing assessment, or human verification).

Primary Workflows

Operator (Implementation)

Focus on evidence-backed delivery.

  • Context: keel story show <id>, keel voyage show <id>, and keel next --role operator.
  • Action: Implement requirements, record proofs with keel story record, and submit.
  • Constraint: Every AC must have a proof, and every implementation story must close with at least one sealing commit before you move on.

Manager (Planning)

Focus on strategic alignment and unblocking.

  • Context: keel epic show <id>, keel roles, keel next --role manager --explain, and keel flow.
  • Action: Author PRD.md, SRS.md, SDD.md, resolve routing, decompose stories, and attach mission children explicitly with keel mission attach <mission-id> --epic <epic-id>, --bearing <bearing-id>, or --adr <adr-id>.
  • Constraint: Move voyages from draft to planned only when requirements are coherent.

Explorer (Research)

Focus on technical discovery and fog reduction.

  • Context: keel bearing list.
  • Action: Fill BRIEF.md, collect EVIDENCE.md, and assess.
  • Constraint: Graduate to epics only when research is conclusive.

Human Interaction & Pokes

Keel's autonomous flow is governed by a physical battery metaphor, but the charge is now derived from real repository activity rather than a synthetic wake file.

If a human user pokes you (e.g., "I'm poking you", "Wake up"), you MUST:

  1. Orient: Execute keel heartbeat, keel health --scene, keel flow --scene, and keel doctor.
  2. Inspect: Run keel mission next --status and keel pulse to identify any new work that has become ready or materialized.
  3. Route if Needed: Use keel roles or keel next --role <role> --explain when lane selection or queue behavior needs clarification.

Autonomous Backlog Discharge

As long as the system is AUTONOMOUS (LIGHT ON) and the circuit is healthy (no blown capacitors), you are responsible for discharging the delivery backlog during the Pull and Ship phases of the turn loop.

  1. Identify Ready Work: Scan the delivery lane for stories in backlog that are not blocked by dependencies.
  2. Autonomous Start: For each ready story, execute keel story start <id>.
  3. Rube Goldberg Loop: Transitioning a story to in-progress mutates the repository, which refreshes the derived heartbeat and keeps the circuit closed while you continue moving work.
  4. Priority: Discharging the backlog is your primary tactical objective once energized. You must continue until the backlog is empty or the circuit trips.
  5. Loop Closure: After every successful implementation or transition, you MUST land a sealing commit that captures the resulting board and code changes. This applies to ALL work, including storyless gardening or engine changes. The pacemaker warning is cleared by committing the dirty worktree, not by touching a synthetic heartbeat file.

Global Hygiene Checklist

Apply these checks to every change before finalizing work:

  1. Doctor First: keel doctor is the ultimate source of truth for board integrity. You MUST run the doctor at the start of every session. If the doctor reports errors or "Short Circuits", you MUST prioritize fixing those diagnostic orders before attempting any other work or architectural changes.
  2. The Health Loop: Use keel health --scene for high-level triage. Subsystems are mapped as follows:
    • NEURAL: Stories (ID consistency, AC completion)
    • MOTOR: Voyages (Structure, SRS/SDD authorship)
    • STRATEGIC: Epics (PRD, Goal lineage)
    • SENSORY: Bearings (Research, Evidence quality)
    • SKELETAL: ADRs (Architecture decisions)
    • VITAL: Missions (Strategic achievement)
    • AUTONOMIC: Routines (Cadence, materialization)
    • CIRCULATORY: Workflow (Graph integrity, topology)
    • PACEMAKER: Heartbeat (derived repository activity and open-loop warning state)
    • KINETIC: Delivery (Backlog liquidity, execution capacity)
  3. Pacemaker Protocol: The system's heartbeat is derived from Git/worktree activity and inspected with keel heartbeat. A clean repo falls back to the latest commit; a dirty repo uses the freshest changed path it can observe. doctor warns when the worktree carries uncommitted energy, and the sealing commit is what clears that warning. The installed pre-commit hook keeps quality checks and tests tied to the commit boundary, and the commit-msg hook appends doctor --status to the message body.
  4. Gardening First: You MUST tend to the garden (fixing doctor errors, discharging automated backlog, and resolving structural drift) BEFORE notifying the human operator or requesting input.
  5. Notification Threshold: Only request human intervention when you reach a "Manual Lane" that requires design direction or a decision on application behavior (e.g., assessing a Bearing, planning a Voyage, or human verification of a complex Story).
  6. Automated Guardrails: You no longer need to run just quality or just test manually before every commit. The git pre-commit hook (installed via keel hooks install) automatically enforces these checks. If a commit fails, resolve the reported lints or test failures and try again.
  7. Lifecycle Before Commit: Run board-mutating lifecycle commands before the atomic commit when they generate or rewrite .keel artifacts (for example story submit, voyage plan, voyage done, bearing assess, bearing lay). After the transition, inspect git status and include the resulting .keel churn in the same commit.
  8. Atomic Commits: Commit once per logical unit of work. Use Conventional Commits:
    • feat: (new feature)
    • fix: (bug fix)
    • docs: (documentation)
    • refactor: (code change, no behavior change)
    • test: (adding/updating tests)
    • chore: (build/tooling)
  9. Story Commit Minimum: Every implementation story needs at least one dedicated sealing commit. Do not carry multiple effectively-complete stories in one dirty worktree. If the change no longer fits one story cleanly, stop and re-scope before continuing.
  10. No Completion Claims Before Commit: Do not report a story, voyage, epic, or mission as complete, executed, achieved, verified, or sealed until the relevant code, proof, and lifecycle changes are committed and the board state matches that claim.
  11. Turn Loop Does Not Override Git Discipline: Heartbeat, pacemaker, and loop-closure guidance exist to force timely commits, not to justify batching unrelated stories or deferring story-level commit boundaries.
  12. Mission Loop Discipline: For mission-driven work, return to the mission steward loop after every completed story, planning unit, or bearing instead of continuing ad hoc from the last worker context.
  13. Knowledge Quality Bar: Prefer no new knowledge over low-signal knowledge. A new knowledge entry should be novel, reusable across stories, and materially reduce future drift; otherwise link existing knowledge or omit capture entirely.

Compatibility Policy (Hard Cutover)

At this stage of development, this repository uses a hard cutover policy by default.

  1. No Backward Compatibility by Default: Do not add compatibility aliases, dual-write logic, soft-deprecated schema fields, or fallback parsing for legacy formats unless a story explicitly requires it.
  2. Replace, Don't Bridge: When introducing a new canonical token, field, command behavior, or document contract, remove the old path in the same change slice.
  3. Fail Fast in Validation: keel doctor and transition gates should treat legacy or unfilled scaffold patterns as hard failures when they violate the new contract.
  4. Single Canonical Path: Keep one source of truth for rendering, parsing, and validation; avoid parallel implementations meant only to preserve old behavior.
  5. Migration Is Explicit Work: If existing board artifacts need updates, handle that in a dedicated migration pass/story instead of embedding runtime compatibility logic.

Commands

Command execution model (DRY)

Use one path for each concern:

  • nix develop for the repository shell and shared tooling.
  • just ... for repo/build/test workflows.
  • keel ... for all board/workflow operations.

just workflow commands

Command Purpose
just List available recipes
just fmt Format the workspace
just fmt-check Check formatting
just clippy Run workspace clippy
just check Run the repo's quality gate
just test [args] Run tests
just doctest [args] Run doc tests
just coverage [args] Produce coverage output
just port ... Run the Port CLI

keel board workflow commands

Run keel --help for the full command tree. The core commands you should rely on:

Category Commands
Orientation keel turn keel heartbeat keel health --scene keel flow --scene keel doctor
Inspection keel mission next [<id>] keel pulse keel roles keel next --role manager --explain
Discovery keel bearing new <name> keel bearing research <id> keel bearing assess <id> keel bearing list
Planning keel epic new "<name>" --problem "<problem>" keel voyage new "<name>" --epic <epic-id> --goal "<goal>"
Execution keel story new "<title>" [--type <type>] [--epic <epic-id> [--voyage <voyage-id>]]
Board Ops keel next --role manager keel next --role operator keel generate keel config show keel mission show <id> keel mission attach <mission-id> --epic <epic-id> keel mission attach <mission-id> --bearing <bearing-id> keel mission attach <mission-id> --adr <adr-id>
Lifecycle Story/voyage/epic transitions in the table below

Story and Milestone State Changes

Use CLI commands only; do not move .keel files manually.

Action Command
Start keel story start <id>
Reflect keel story reflect <id>
Submit keel story submit <id>
Reject keel story reject <id> "reason"
Accept keel story accept <id> --role manager
Ice keel story ice <id>
Thaw keel story thaw <id>
Voyage plan keel voyage plan <id>
Voyage done keel voyage done <id>