project-status

Project status — interactive HTML tracker

Generate or maintain project_status.html in the project root. The page is a static, self-contained HTML document with an interactive pipeline-of-parts view: click a part to see what shipped and what's pending. Designed to live in the repo, be opened directly in a browser, and stay current as work progresses.

Decide the mode

Look in the target directory (default: cwd; if $ARGUMENTS is a path, use that):

• No project_status.html → create mode.
• Existing project_status.html → update mode.
• $ARGUMENTS literal "create" or "update" → force that mode.

Create mode

1. Gather project signals

Read just enough to understand the project's structure. Highest-signal sources, in order:

• README.md — section headings usually map directly to the main parts.
• Manifest: package.json / pyproject.toml / Cargo.toml / Gemfile / go.mod — project name, dependencies.
• Top-level directories: ls -1 or Glob for */.
• Recent work: git log --oneline -50.
• Agenda files: TODO*, ROADMAP*, AGENDA*, NEXT_STEPS*, planning docs in docs/.

Don't read every file. Read the cues.

2. Choose 4–10 main parts

These are the cards on the page. Pick parts that match the user's mental model:

• CLI tool → arg parsing, dispatch, core logic, output, tests
• Web app → API routes, data, frontend, auth, deployment
• Pipeline → ingest, process, score, alert (the watchtower shape)
• Library → public API, internal modules, tests, docs, build

README section structure is usually the right answer. Otherwise top-level dirs.

3. Fill in each part

For each, draft:

{
  id: "kebab-case-slug",
  num: "01",                  // two-digit display
  name: "Short Title",
  blurb: "One-line card summary, ≤90 chars.",
  detail: "1–2 sentence panel intro.",
  shipped: [
    ["item description (HTML allowed: <code>foo</code>)", "ref: sha / cycle 18 / 2026-05-13"],
    ["another shipped item", ""]
  ],
  pending: [
    ["carry-forward item", "next pass"]
  ]
}

Be specific. "Data layer" is weak; "Postgres schema + migrations + connection pool" is strong. If a section has nothing pending, use [["No active carry-forwards"]] (single entry, no ref).

4. Render the template

Read ${CLAUDE_SKILL_DIR}/templates/project_status.html. Substitute these placeholders:

Placeholder	What to put
{{PROJECT_NAME}}	Project name from manifest or README h1
{{EMPHASIS_WORD}}	One word to render in italic clay color. Pick what reads best italicized — e.g. "status", or a word from the project name.
{{SUBTITLE}}	One sentence under the h1. Mention number of parts and invite click.
{{SNAPSHOT_DATE}}	Today, YYYY-MM-DD (use the current date from the environment)
{{STAGES_JSON}}	The populated STAGES array as JavaScript literal (not strict JSON — strings can contain <code> HTML). Use double-quoted keys and values, escape </script> as <\/script> if it appears in any string.
{{FOOTER}}	One-line footer. If nothing project-specific, use: Generated by /project-status. Update by re-invoking the skill or editing the STAGES array directly.

Write the result to <target>/project_status.html.

5. Drop the tracking note

Read ${CLAUDE_SKILL_DIR}/assets/claude_md_tracking.md. Append it to <target>/CLAUDE.md:

• If CLAUDE.md doesn't exist, create it with the snippet as the only content (no preceding blank lines).
• If CLAUDE.md exists but doesn't contain the heading ## Project status tracking, append the snippet with a blank line before it.
• If the heading is already present, skip — don't duplicate.

6. Report back

One sentence. Path written, number of stages, mode. Example:

Wrote project_status.html (7 parts, create mode). Added tracking note to CLAUDE.md.

Update mode

1. Read the current file

Read the existing project_status.html. The STAGES = [...] array lives in the <script> block near the bottom.

2. Find recent work

Extract Snapshot YYYY-MM-DD from the header. Then:

git log --since="<that-date>" --oneline

…to see what's been merged since. Also scan any change notes the user might have written in the conversation.

3. Surgical edits only

Use the Edit tool. For each meaningful change:

• Move the matching pending entry into shipped (with a fresh ref — short SHA, cycle number, date).
• If no matching pending exists, append a new shipped entry.
• Add to pending only if the user explicitly mentioned new agenda items.

Bump Snapshot YYYY-MM-DD in the header subtitle to today.

Do not regenerate the file, reorder stages, drop user-curated entries, or touch the styling. Only the data inside STAGES and the snapshot date.

4. Report back

One sentence. Stages touched, mode. Example:

Updated project_status.html (3 stages touched, snapshot bumped to 2026-05-13).

Notes & guardrails

• The STAGES data is JavaScript inside <script>, not JSON. Strings can contain HTML (<code>…</code>). This is intentional — it keeps the page a single self-contained file with no external data fetch.
• The template's CSS custom properties (--ivory, --clay, --olive, etc.) are the skill's visual identity. Don't change the palette.
• The page is fully static: no external JS, no fonts, no analytics. Anything that needs internet is out of scope.
• If the user passes a path in $ARGUMENTS that doesn't exist, exit early and ask them to clarify.