instar-project

/project — Multi-Spec Project Surface

Spec: docs/specs/PROJECT-SCOPE-SPEC.md § Phase 1.7. A project bundles many feature initiatives into rounds. The dashboard Projects tab, the session-start digest, and the compaction-recovery hook keep them visible. This skill is the user-invocable surface for inspecting and driving them.

Setup — read auth + port once

AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null)
PORT=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('port',4040))" 2>/dev/null)

Every endpoint except /health requires Authorization: Bearer $AUTH.

/project create <plan-doc-path>

Register a new project from a plan-doc markdown file. The plan-doc schema is PlanDocParser's contract (spec § Phase 1.6).

Pre-flight first (no rate-limit cost):

curl -sS -X POST -H "Authorization: Bearer $AUTH" \
  -H "Content-Type: application/json" \
  -d "{\"planDocPath\": \"$(realpath PLAN_DOC.md)\"}" \
  "http://localhost:${PORT}/projects/validate"

Returns 200 {ok, project, children, errors}. Iterate until ok:true.

Then create:

curl -sS -X POST -H "Authorization: Bearer $AUTH" \
  -H "Content-Type: application/json" \
  -d "{\"planDocPath\": \"$(realpath PLAN_DOC.md)\"}" \
  "http://localhost:${PORT}/projects"

• 201 — {project, children}.
• 400 — validation failed; surface each error.
• 409 — slug already exists.
• 429 — rate-limited (5 creates/hour per auth token); body includes windowEnds.

/project status [id]

No id — list all projects:

curl -sS -H "Authorization: Bearer $AUTH" "http://localhost:${PORT}/projects"

Render to user: id, title, per-round status summary (e.g. 2/4 complete, 1 in-progress, 1 pending).

With id — fetch the project plus its child items:

curl -sS -H "Authorization: Bearer $AUTH" "http://localhost:${PORT}/projects/<id>"