| name | oat-project-next |
| version | 1.0.4 |
| description | Use when continuing work on the active OAT project. Reads project state, determines the next lifecycle action, and invokes the appropriate skill automatically. |
| disable-model-invocation | true |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Bash(git:*), Skill |
Project Next
Stateful router for the OAT project lifecycle. Reads project state and invokes the appropriate next skill.
Prerequisites
- Active OAT project set in
.oat/config.local.json (activeProject), or at least one project directory in the projects root
Mode Assertion
OAT MODE: Routing
Purpose: Read project state and dispatch to the correct next lifecycle skill. Never mutate project state.
BLOCKED Activities:
- ❌ No modifying state.md, plan.md, implementation.md, or any project artifact
- ❌ No executing implementation tasks
- ❌ No creating or modifying review artifacts
ALLOWED Activities:
- ✅ Reading all project artifacts and frontmatter
- ✅ Scanning the reviews/ directory
- ✅ Invoking the determined target skill via the Skill tool
Self-Correction Protocol:
If you catch yourself:
- Modifying any project file → STOP (this skill is read-only)
- Making a routing decision without reading state → STOP (always read state.md first)
Recovery:
- Acknowledge the deviation
- Re-read project state
- Route based on the algorithm below
Progress Indicators (User-Facing)
-
Print a phase banner once at start:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OAT ▸ NEXT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
Print each step indicator at the start of that step, not all at once upfront:
[1/6] Resolving active project…[2/6] Reading project state…[3/6] Classifying artifact state…[4/6] Checking for unprocessed reviews…[5/6] Routing to target skill…[6/6] Invoking {target-skill}…
Behavioral Notes
This skill is purely a reader and dispatcher — it never mutates project state. All state mutations are handled by the target skill it invokes.
Relationship to oat-project-progress: Progress is a read-only diagnostic that outputs a status report and recommendation. This skill reads the same state and dispatches to the recommended skill directly. They are complementary. A user running progress then next may see different recommendations for "Tier 2" states (see Boundary Detection below) — this is intentional and by design.
Process
Step 0: Resolve Active Project
PROJECT_PATH=$(oat config get activeProject 2>/dev/null || true)
PROJECTS_ROOT="${OAT_PROJECTS_ROOT:-$(oat config get projects.root 2>/dev/null || echo ".oat/projects/shared")}"
PROJECTS_ROOT="${PROJECTS_ROOT%/}"
If PROJECT_PATH is missing or invalid (directory does not exist):
Check whether any projects exist:
ls -d "$PROJECTS_ROOT"/*/ 2>/dev/null
If PROJECT_PATH is valid: derive {project-name} as the basename of the path.
Step 1: Read Project State
Read "$PROJECT_PATH/state.md" frontmatter and extract:
| Field | Used For |
|---|
oat_phase | Current lifecycle position (discovery, spec, design, plan, implement) |
oat_phase_status | Phase completion state (in_progress, complete, pr_open) |
oat_workflow_mode | Routing table selection (spec-driven, quick, import). Default: spec-driven |
oat_hill_checkpoints | Which phases require HiLL approval |
oat_hill_completed | Which HiLL gates have been passed |
oat_blockers | Informational warnings (not routing gates) |
If state.md is missing or unreadable: Report error and suggest running the relevant phase skill directly. STOP.
Map oat_phase to the current artifact file:
| Phase | Artifact File |
|---|
discovery | discovery.md |
spec | spec.md |
design | design.md |
plan | plan.md |
implement | implementation.md |
Read the artifact frontmatter and extract:
| Field | Used For |
|---|
oat_status | Tier 1 detection (complete vs in_progress) |
oat_ready_for | Direct routing target (skill name or null) |
oat_template | Tier 3 detection (true = still a template) |
If artifact file is missing: Treat as tier 3 (template) — route to the current phase skill.
Step 2: Classify Artifact State (Boundary Detection)
Apply the following tiers in order:
Tier 1 (Complete with target):
oat_status == "complete" AND oat_ready_for is not null- → Use
oat_ready_for as the target skill
Tier 1b (Complete without target):
oat_status == "complete" AND oat_ready_for is null- → Route to the NEXT phase's skill (the artifact is complete, so advance)
- This handles cases where a phase skill completed the artifact but didn't set
oat_ready_for.
Tier 2 (Substantive content):
oat_status == "in_progress"- AND
oat_template is NOT true (field is absent or false)
- AND the artifact does NOT contain template placeholders (fallback check: patterns like
{Project Name}, {Copy of user's initial request}, {Clear description)
- → Route to the NEXT phase's skill (the downstream skill handles marking the current phase complete)
Tier 3 (Template/Empty):
oat_template == true- OR the artifact contains template placeholder patterns
- OR the artifact file does not exist
- → Route to the CURRENT phase's skill (resume mid-work)
Primary signal: The oat_template frontmatter field. Templates from .oat/templates/ include oat_template: true; phase skills set it to false when they begin working.
Fallback heuristic: Only needed when oat_template is missing. Check for {Project Name} in the title or {Copy of / {Clear description in section content.
Step 3: Route to Target Skill
Step 3a: HiLL Gate Override (applied first)
If oat_phase is in oat_hill_checkpoints AND NOT in oat_hill_completed:
→ Route to the current phase's skill regardless of boundary tier or phase status.
→ Announce: "HiLL gate pending — routing to current phase for approval."
Phase-to-skill mapping for HiLL override:
| Phase | Skill |
|---|
| discovery | oat-project-discover |
| spec | oat-project-design |
| design | oat-project-design |
| plan | oat-project-plan |
Note: a spec HiLL phase only appears in legacy projects scaffolded before requirements confirmation was folded into oat-project-design. New projects scaffold with ['discovery', 'design'] HiLL checkpoints, so spec falls through to oat-project-design here as a graceful migration. The standalone oat-project-spec skill remains available as an opt-in for users who want to formalize requirements separately.
Note: implement is intentionally omitted. Implementation-phase checkpoints are handled by oat_plan_hill_phases in plan.md (plan-phase-level gates), not by the workflow-level oat_hill_checkpoints in state.md.
Step 3b: Phase Routing Tables
If oat_phase == "implement" AND (oat_phase_status == "complete" OR oat_phase_status == "pr_open"):
→ Skip to Step 5: Post-Implementation Router
Otherwise, look up the target skill from the routing table for the current oat_workflow_mode:
Spec-Driven Mode (default):
| Current Phase | Phase Status | Boundary Tier | Target Skill |
|---|
| discovery | in_progress | tier 3 (template) | oat-project-discover |
| discovery | in_progress | tier 2 (substantive) | oat-project-design |
| discovery | complete | tier 1 | oat-project-design |
| spec | in_progress | tier 3 | oat-project-design |
| spec | in_progress | tier 2 | oat-project-design |
| spec | complete | tier 1 | oat-project-design |
| design | in_progress | tier 3 | oat-project-design |
| design | in_progress | tier 2 | oat-project-plan |
| design | complete | tier 1 | oat-project-plan |
| plan | in_progress | tier 3 | oat-project-plan |
| plan | in_progress | tier 2 | oat-project-implement * |
| plan | complete | tier 1 | oat-project-implement * |
| implement | in_progress | — | oat-project-implement * |
Quick Mode:
| Current Phase | Phase Status | Boundary Tier | Target Skill |
|---|
| discovery | in_progress | tier 3 | oat-project-discover |
| discovery | in_progress | tier 2 | oat-project-plan |
| discovery | complete | tier 1 | oat-project-plan |
| plan | in_progress | tier 3 | oat-project-plan |
| plan | in_progress | tier 2 | oat-project-implement * |
| plan | complete | tier 1 | oat-project-implement * |
| implement | in_progress | — | oat-project-implement * |
Import Mode:
| Current Phase | Phase Status | Boundary Tier | Target Skill |
|---|
| plan | in_progress | tier 3 | oat-project-import-plan |
| plan | in_progress | tier 2 | oat-project-implement * |
| plan | complete | tier 1 | oat-project-implement * |
| implement | in_progress | — | oat-project-implement * |
* oat-project-implement handles both sequential and parallel execution.
Step 4: Check for Unprocessed Reviews (Review Safety Check)
Before dispatching the target skill, check for unprocessed review artifacts:
Step 1: Scan {PROJECT_PATH}/reviews/ directory (exclude archived/ subdirectory).
- If no files found → skip, proceed to dispatcher.
Step 2: Cross-reference against plan.md Reviews table (if it exists):
- Status
"passed" → processed (review completed successfully)
- Status
"fixes_added" or "fixes_completed" → processed (review-receive already converted findings to tasks)
- Any other status (blank,
"pending", "in_progress", "received") → UNPROCESSED
- File exists in
reviews/ but has NO entry in the Reviews table → UNPROCESSED
Step 3: If any unprocessed reviews exist → override routing target to oat-project-review-receive. Announce: "Unprocessed review feedback detected — routing to review-receive first."
Design note: This expands beyond the spec's original definition of "processed" (which only listed passed) to include fixes_added and fixes_completed, because re-invoking review-receive on already-processed reviews would be redundant.
Step 5: Post-Implementation Router
Entry condition: oat_phase == "implement" AND (oat_phase_status == "complete" OR oat_phase_status == "pr_open")
Apply the following checks in priority order. Stop at the first match:
5.1: Incomplete revision tasks
Grep plan.md for p-revN phases. If any p-revN tasks exist with status != completed in implementation.md:
→ Route to oat-project-implement
→ Announce: "Revision tasks pending — continuing implementation"
5.2: Unprocessed reviews
Run the Review Safety Check (Step 4 above). If unprocessed reviews exist:
→ Route to oat-project-review-receive
→ Announce: "Unprocessed review feedback detected"
5.3: Final code review not passed
Parse plan.md Reviews table for a row with Scope="final" and Type="code":
-
If no such row exists, OR row exists with Status="pending":
→ Route to oat-project-review-provide (with scope hint: "code final")
→ Announce: "Implementation complete — triggering final code review"
-
If row exists with Status="fixes_completed":
→ Route to oat-project-review-provide (with scope hint: "code final")
→ Announce: "Review fixes implemented — triggering re-review"
-
If row exists with other non-passed status (e.g., "received", "fixes_added"):
→ Route to oat-project-review-receive (review findings not yet converted to tasks)
→ Announce: "Final review in progress — continuing review cycle"
-
If row exists with Status="passed":
→ Continue to 5.4
5.4: Summary not done
Read {PROJECT_PATH}/summary.md:
- If file doesn't exist OR
oat_status != "complete":
→ Route to oat-project-summary
→ Announce: "Final review passed — generating project summary"
5.5: PR not created
If oat_phase_status != "pr_open":
→ Route to oat-project-pr-final
→ Announce: "Summary complete — creating final PR"
5.6: PR is open
If oat_phase_status == "pr_open":
→ Route to oat-project-complete
→ Announce: "PR is open — ready to complete project"
Step 6: Announce and Invoke
Print the routing announcement:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OAT ▸ NEXT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project: {project-name}
Current: {oat_phase} ({oat_phase_status}) — {boundary tier or post-impl step description}
Routing: → {target-skill-name}
Reason: {one-line explanation}
Blocker warning: If oat_blockers is non-empty, add before the routing line:
⚠️ Blockers: {blocker descriptions}
The router still dispatches (blockers are informational, not gates).
Invoke the target skill using the Skill tool. The agent will load the skill content and follow it directly.
Success Criteria
- ✅ Active project resolved (or clear error with guidance if none set)
- ✅ State.md and artifact frontmatter read correctly
- ✅ Boundary tier classified correctly (complete / substantive / template)
- ✅ HiLL gates respected (not bypassed)
- ✅ Unprocessed reviews caught before advancing
- ✅ Correct target skill invoked for the current workflow mode and phase
- ✅ Routing announcement displayed before dispatch
