project-builder

Project Lifecycle Agent plugin for Claude Code. Extends the idea of a one-shot "Workflow Builder" into a persistent Project Operating System: discovery, requirements, architecture, workflow, task planning, and review, all tracked in a .project/ state directory so work can be resumed, reviewed, and changed without re-planning from scratch.

Install

Claude Code:

/plugin marketplace add /path/to/project-builder
/plugin install project-builder

Codex: the skill is also exposed via .codex-plugin/plugin.json (skills: ./skills/). The /project slash command is Claude Code-only — Codex users invoke the skill through natural language.

Use

Natural language ("프로젝트 시작하자", "다음 뭐 해야 돼?", "이 기능 추가하자", "프로젝트 점검해줘") or the /project command (Claude Code only):

/project status         # 현재 상태 요약
/project next            # 다음에 할 작업 추천 + 이유 + 대안
/project do [TASK-id]     # Task 구현 → 증거 기록 → DONE 전이
/project plan             # discovery → requirements → architecture → workflow → tasks
/project review           # coverage / drift / validation 점검
/project requirements     # requirements.md 조회·갱신
/project architecture     # architecture.md 조회·갱신
/project tasks             # 전체 task 상태 요약

How it works

Everything lives under .project/ in the target repository:

.project/
├── PROJECT.md       # stable facts
├── STATE.md         # current status — read every session
├── requirements.md  # REQ-xxx
├── architecture.md  # system structure
├── decisions.md     # DEC-xxx, append-only
├── workflow.md        # phases + exit criteria
└── tasks/
    ├── backlog/ active/ done/   # TASK-xxx.md with YAML frontmatter

skills/project-builder/scripts/tasks.py computes the task graph deterministically instead of asking the model to eyeball frontmatter: it parses only YAML-lite frontmatter (never task bodies), and returns which tasks are ready (already sorted by blocking power → priority → phase — ready has no dependency-order constraint between its entries, though concurrent execution across them still needs the isolation rules in execute.md), which are blocked and why, a req_coverage index (REQ id → linked tasks + whether they're all DONE), the next_task_id to allocate, and structural issues — each tagged critical/warning/info (cycles, missing deps, duplicate ids, malformed frontmatter, status/folder mismatches, etc.) — so callers act on severity instead of a hardcoded type list. No third-party dependencies; python3 tasks.py --selftest runs its own fixture-based checks (23 as of this writing). See skills/project-builder/references/ for the full protocol.

v1 scope

project-orchestrator + project-discovery + requirements-builder + architecture-builder + workflow-builder + task-builder + execute (TASK → evidence-backed DONE loop) + project-reviewer + change-manager, unified as capabilities of a single skill (skills/project-builder/) rather than eight-plus competing skills.

Not yet implemented (v2/v3 candidates): project-research, test-planner, release-manager, documentation-manager, decision-manager (standalone), risk-manager (standalone — risk tracking itself lives in templates.md + next-action.md), drift-detector (standalone), project-health (standalone scoring — /project status answers with 3 raw values instead, see commands/project.md).

CI/CD

.github/workflows/ci.yml runs on every PR and push to main:

• python3 skills/project-builder/scripts/tasks.py --selftest — the task-graph engine's own regression suite.
• NVIDIA/SkillSpector scan skills/project-builder --no-llm — static security scan (AST + taint tracking + YARA + OSV.dev), SARIF uploaded to the repo's Security tab. Gate: exit 0 (risk score ≤ 50) passes, 1/2 fails.
• NVIDIA/SkillEvaluator validate skills/project-builder --checks schema,pii,license,quality,unicode,lint --no-dedup — Tier 1 deterministic quality/schema/PII checks.

Both tools run keyless (--no-llm / --no-dedup, no API keys, no Docker) — this is intentionally the static-only layer. Two findings are known and reviewed rather than blocking: SkillSpector flags no allowed-tools scope declared (SKILL.md intentionally leaves tool scope open) and a benign "regardless of language" line as an anti-refusal pattern (false positive, score already passes at 24/100).

Reproduce locally:

python3 skills/project-builder/scripts/tasks.py --selftest
uv tool install "git+https://github.com/NVIDIA/SkillSpector.git@<pinned SHA — see ci.yml>"
skillspector scan skills/project-builder --no-llm
uv tool install --python 3.13 "skillevaluator[all] @ git+https://github.com/NVIDIA/SkillEvaluator.git@<pinned SHA — see ci.yml>"
skillevaluator validate skills/project-builder --checks schema,pii,license,quality,unicode,lint --no-dedup

.github/workflows/release.yml triggers on v* tags: verifies the tag matches version in both .claude-plugin/plugin.json and .codex-plugin/plugin.json, re-runs the CI gates, then publishes a GitHub Release with a git archive source tarball and the SkillSpector report attached.

Neither upstream tool has tagged releases yet, so both are pinned to a resolved commit SHA in the workflow env: block — bump by re-resolving git ls-remote <repo> main.

Deferred (v2 candidates, each needs an API key, Docker, or a signing key this repo doesn't have): SkillSpector's LLM semantic pass, SkillEvaluator Tier 2 (semantic dedup) and Tier 3 (live agent A/B eval), and OpenSSF model_signing (skill.oms.sig — NVIDIA's own root cert chain isn't reusable by third parties).