State Manager Skill

This skill is the utility layer that other skills use to interact with the .hackathon/ state system.

Core Operations

Read State

Read .hackathon/STATE.md and parse:

• Active phases (from active-phases array)
• Phase completion status for all phases (including skipped)
• Team roster
• Active blockers
• Time remaining (computed from start/end times)

Check Gate

Delegate to .hackathon/bin/check-gate.py — this script is the single canonical source for all gate rules, including which phases are prerequisites and which output files must exist. Do not re-specify gate rules in this skill or elsewhere; call the script and use its output.

python3 .hackathon/bin/check-gate.py <phase-name>

The script returns JSON with pass, missing_phases, missing_files, and warnings. Use these to inform the user what's blocking and what's needed.

Update Phase

When a phase completes:

1. Set the phase's status to "complete" in STATE.md (use inline format: status: "complete")
2. Set the phase's completed-at to current timestamp
3. Update active-phases: remove the completed phase, add the next unblocked phase(s) (use inline array format: active-phases: ["architect", "stack"])
4. If all planning phases are complete and it's time for feature development, set mode: "building"
5. Append to log/changelog.md: "[timestamp] Phase [name] completed"

STATE.md formatting contract: Always write STATE.md frontmatter values as single-line key: value pairs. Arrays must use inline format (["a", "b"]), never multi-line YAML sequences. This ensures the simple frontmatter parser in the helper scripts can always read the file correctly.

Log Decision

Append to log/decisions.md with timestamp, who, and what was decided.

Log Blocker

Add/remove from log/blockers.md and STATE.md's active-blockers list.

Document Schema Validation

Schema validation is directory-aware and warn-only — it flags issues but never blocks progress.

Strict frontmatter (all fields required: owner, status, created-at, last-modified, phase):

• .hackathon/IDEA.md, IDEA-FINAL.md, FEASIBILITY.md, ARCHITECTURE.md, STACK.md, DEMO-SCRIPT.md, PLAN.md
• .hackathon/specs/*.md
• .hackathon/contracts/*.md (not .ts files)
• .hackathon/design/*.md

Minimal frontmatter (owner/slug required, other fields optional):

• .hackathon/tasks/*.md

No frontmatter required:

• .hackathon/log/*.md (append-only logs)
• .hackathon/bin/* (scripts)
• .hackathon/mockups/* (HTML files)
• .hackathon/contracts/*.ts (TypeScript files)
• .hackathon/stack-config.json

See skills/state-manager/references/document-schemas.md for the full field definitions per document type.