project-loop-builder

name	project-loop-builder
description	Turn a large software project or feature set into epic-scoped developer loops with testable task contracts, local or cloud CI/CD gates, review/fix cycles, PR babysitting, and human approval only at real gates. Use when planning how agents should decompose, build, verify, review, document, and hand off a large project without bothering the human after every passing task.

Project Loop Builder

Use this skill to convert broad work into professional developer loops.

Core Model

• One project is split into phases.
• One phase is promoted into one active epic.
• One epic contains ordered tasks.
• One task gets one full story loop: plan tests, implement, verify, review, fix, document, and gate.
• Passing task loops record evidence and continue to the next task in the same epic without human interruption.
• A judge agent reviews each task diff and evidence before the commit is allowed to advance; the judge approves or sends it back to the fix loop.
• The human-facing task-complete signal/tool call and local visible notification fire only when the active epic is closed, blocked, or parked.
• Merge, fresh-epic start, push, PR, live spend, dependency install, destructive cleanup, parallel coding lanes, and prod/release promotion stay explicit human gates.

Required Output Contract

Every loop plan produced by this skill must include:

• phase map
• epic table
• task/story table
• per-task contract cards
• verification matrix
• review/fix loop
• judge-agent approval loop
• PR babysitter loop
• epic-completion notification or popup
• local-CI convention for this environment
• generalized cloud-CI variant for future projects
• human gates and automation boundaries

Use references/output-shape.md as the canonical section order when a user asks for an implementation plan or loop set.

Workflow

1. Verify repo truth: cwd, branch, upstream, dirty state, package manager, remote refs, and local-vs-cloud CI convention.
2. Define the completion target in one sentence.
3. Map phases, then promote only one active epic.
4. Write each task as a testable contract:
   • user outcome
   • exact write scope
   • tests before edits
   • acceptance criteria
   • review lanes
   • stop rule
5. For each task, run the full story loop.
6. For PRs, babysit until all checks/reviews are resolved:
   • local convention: rerun local CI/CD and route the diff through a judge agent before the commit advances
   • cloud convention: watch PR checks/reviews, address comments, rerun failed jobs, route the resulting diff through the judge, and keep the diff intentional
7. At epic closure, present the human with the merge/continue gate and trigger the configured local completion notification: branch, SHA, checks, review findings, residual risk, and next epic recommendation.

Task Contract Fields

Each task must define:

• user outcome
• exact write scope
• tests before edits
• acceptance criteria
• review lanes
• stop rule

In Obscura, use docs/roadmap/templates/epic-template.md and docs/roadmap/templates/task-card-template.md when those durable roadmap templates are present. For non-Obscura projects, use the project's own issue, roadmap, or planning docs; when no durable tracker exists, use references/loop-plan-template.md as the lightweight conversation template.

Convention Modes

• Obscura local-CI mode: load references/obscura-local-ci.md when working in this repo or another Jeff local-CI environment.
• Generalized cloud-CI mode: load references/general-cloud-ci.md when planning a shareable or conventional GitHub PR workflow.
• Do not mix modes in a gate packet. Name the selected mode, then keep its verification, PR babysitter, judge reroute, and human gates internally consistent.

Validation

Before claiming the skill package is complete:

• Run python C:\Users\jeffk\.codex\skills\.system\skill-creator\scripts\quick_validate.py .agents\skills\project-loop-builder on Jeff's machine.
• Run the focused skill packaging test.
• Keep SKILL.md concise enough for fast loading and update agents/openai.yaml when trigger language changes.

For Obscura, align with:

• scripts/dev-cycle.mjs
• docs/roadmap/epic-operating-system.md
• docs/roadmap/epic-delivery-board.md
• docs/roadmap/templates/epic-template.md
• docs/roadmap/templates/task-card-template.md