Implement Stage 6 Builder Pro plan , srs-v0.8.0 - #63
Merged
Conversation
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
* refactor(pro-tier): normalize Stage 1-3 Pro agents to thin-router pattern (#61)
* (resolve) merge conflict (#60)
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* refactor(pro-tier): normalize Stage 1-3 Pro agents to thin-router pattern
Stages 1-3 (SRS, Product, Architect) carried their full domain logic
inline in the agent/skill files, unlike Stages 4/5/sprint which already
follow a proven thin-router shape: a ~130-line agent that points at five
numbered reference docs, with the orchestration skill doing gating/state
only. Bring the remaining stages in line so every Pro-tier stage loads
and behaves the same way.
- agents/requirements-analyst-pro.md: 616 -> 81 lines; domain content
moved to references/srs/01-05.md
- agents/product-designer-pro.md: 347 -> 122 lines; domain content moved
to references/product/01-05.md; skills/forge-product-pro/SKILL.md lost
its inline Step 1-16 workflow duplication and Behavioral Rules section
- agents/system-architect-pro.md: 371 -> 129 lines; skills/forge-arch-pro/SKILL.md:
555 -> 222 lines. references/architect/{artifact-specs,identifiers-traceability,
validation-rules,workflow-steps}.md renumbered into 01-05.md, folding in
content that only existed in the skill's inline Phase 1/2 duplication
(Profile Extensions, an API-ownership fail condition, a 13th quality gate)
Verified with the fingerprint-diff method from the sprint-plan refactor
(PR #56): every flagged "missing" block was reformatting, not lost
content. No classic (non-pro) agent/skill touched.
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Formalizes docs/builder-pro-plan-analysis.md's Recommended Execution Plan (Phase 1 only) into REQ-IDs and a 6-task DAG (T-235..T-240): decompose the Stage 6 monolith into 3 focused sub-agents (Context Loader, Code Generator, Quality Gate Runner) wired in-session through the existing forge-build skill. Explicitly defers everything else in the original BUILDER_PRO-PLAN.md (traceability, recovery/resumability, enterprise artifacts, AI-agnostic adapters, extra builder modes) per the analysis's own risk assessment. Ref: T-235..T-240
Read-only persona (allowed-tools: [Read, Grep, Glob]) that resolves only the docs/sections relevant to a given task ID — task-dag entry, matching technical-spec section, referenced architecture/interface/DTO excerpts, applicable profile additional_criteria — instead of the full project context. Task resolution is folded in (no separate Task Resolver agent), per the trimmed decomposition in docs/builder-pro-plan-analysis.md. Ref: T-235
Narrowed persona (allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]) that consumes a Context Loader bundle plus a task definition and writes production code and tests only — no context resolution, no commit, no progress tracking, no gate-running. Sits between Context Loader and Quality Gate Runner in the forge-build pipeline, per docs/builder-pro-plan-analysis.md's trimmed decomposition. Ref: T-236
Single persona (allowed-tools: [Bash, Read]) chaining compile -> lint -> test -> static analysis plus profile additional_criteria, reusing existing project-detected commands. Reports pass/fail per check, never a single aggregate boolean. Explicitly one agent, not four separate Linter/Static-Analyzer/Build-Runner personas, per docs/builder-pro-plan-analysis.md's correction of the original 13-sub-agent proposal. Ref: T-237
Per user direction: keep skills/forge-build/SKILL.md and agents/builder.md completely untouched, and instead add a new, separate Pro tier for Stage 6 — matching the coexistence pattern already used by every other stage (forge-plan-pro, forge-spec-pro, forge-arch-pro, forge-product-pro, forge-sprint-pro, forge-srs-pro). agents/builder-pro.md orchestrates the three sub-agents from T-235..T-237 by adopting each one in sequence (Context Loader -> Code Generator -> Quality Gate Runner), the same in-session persona-swap technique agents/orchestrator.md uses across full pipeline stages, scoped down to Stage 6's three sub-agents. skills/forge-build-pro/SKILL.md is the thin orchestration wrapper (stage gating, profile loading, current-task resolution, commit + progress tracking, state advancement) mirroring skills/forge-plan-pro/SKILL.md's structure, that adopts builder-pro and acts on its all-checks-passed verdict. /forge:build (original) and /forge:build-pro (new) are independent and coexist; selecting one never touches the other's files. Ref: T-238
AC-BUILDPIPE-001a: builder-pro.md references the three sub-agents in order; forge-build-pro/SKILL.md references builder-pro.md; all three sub-agent files exist. AC-BUILDPIPE-001b: skills/forge-build/SKILL.md and agents/builder.md are diffed byte-for-byte against 6a22fa1 (the commit immediately before this feature's planning commit) and must be identical -- and neither file may mention any of the new sub-agent or builder-pro filenames. A future edit that re-wires the original skill/agent into the Pro pipeline fails this test, not just code review. Ref: T-239
User direction mid-build: keep skills/forge-build/SKILL.md and agents/builder.md exactly as they were; ship the sub-agent pipeline as a new forge-build-pro skill + builder-pro agent instead, matching the coexistence pattern already used by every other stage's Pro tier. Revises REQ-BUILDPIPE-001 and T-238's description/done-when in the v0.8.0 SRS and task-DAG to match what was actually built (T-238 commit 32b5a1d, T-239 commit fc65753). Ref: T-238
Full sweep after T-235..T-239: 1925 unit tests pass, validate-plugin.py 0, full-pipeline.sh 12/12 stage gates + traceability chain intact. Updates build/05-implementation/progress.md's Current State to COMPLETE with commit refs, adds a CHANGELOG [Unreleased] entry for the Builder Pro tier, and records two lessons: verify a session-limited subagent's actual disk/test state before assuming its task failed, and check for an existing Pro-tier coexistence pattern before rewiring a live skill in place. Ref: T-240
Revision 2. Revision 1 scoped this feature from docs/builder-pro-plan-analysis.md's trimmed recommendation (3 sub-agent persona files orchestrated by in-session persona-swapping) and shipped it as T-235..T-240. That was the wrong shape: BUILDER_PRO-PLAN.md's own appended Phase 2 section (Phase 0 fix-and-register-Pro and Phase 1 thin-router-stages-1-3 are both already done -- #62) specifies a script + thin-agent split instead, since context resolution and gate execution are deterministic/mechanical, not generative work needing an LLM persona: agents/builder-pro.md ~130 lines, thin router references/build/01..05-*.md foundation, context-resolution, execution-verification, traceability, workflow-governance skills/forge-build-pro/SKILL.md orchestration only, zero domain logic scripts/build_executor.py deterministic engine, reuses parallel_build.py Rescopes T-241..T-251: remove Revision 1's three sub-agent files, author the five reference docs, rewrite builder-pro.md as a thin router, build build_executor.py, rewrite forge-build-pro/SKILL.md to actually call it, and re-verify skills/forge-build/SKILL.md + agents/builder.md stay untouched. Ref: T-241..T-251
Deletes the three Revision-1 sub-agent persona files (context-loader, code-generator, quality-gate-runner) and their tests. BUILDER_PRO-PLAN.md's actual Phase 2 section specifies context-resolution and gate-execution as deterministic script logic (scripts/build_executor.py, T-248), not LLM personas. Their domain content carries forward into references/build/02-context-resolution.md (T-243) and references/build/03-execution-verification.md (T-244). Full unit suite green (1886 passed), no dangling references to the removed files anywhere in code or tests. Ref: T-241
BUILDER_PRO-PLAN.md's own per-task pipeline ends Commit -> Progress Tracking -> Traceability Update. srs-v0.8.0.md and task-dag-v0.8.0.md documented the traceability-update step in prose but never gated it with an acceptance criterion, so T-248's "Done when" list omitted it. Every other Stage 1-5 Pro tier already treats traceability as mandatory, not deferred (references/srs|product|architect|spec|plan|sprint-plan/ each ship a traceability-validation file) — this closes the same gap for Builder Pro. Reuses scripts/traceability-check.py's existing chain format rather than a parallel one. Adds T-248's dependency on T-245. Ref: T-248
Marks Revision 1 (T-235..T-240) as superseded and records T-241 done + the AC-BUILDEXEC-001d gap-fix, per session-hygiene rule (update progress.md as work happens, not at the end). Ref: T-241
Builder Pro foundation: role/mission as Execution Orchestrator (not a coding agent), stage ownership boundary vs Stages 1-5 and vs Classic builder.md, script/agent split of labor, identifier conventions, and the scoped-down two-artifact output contract (build-log.jsonl + progress.md, not BUILDER_PRO-PLAN.md's original eleven-file set). Ref: T-242
Documents the task -> module -> interfaces -> DTO -> requirements -> minimal-load algorithm scripts/build_executor.py implements, and the context bundle field shape (carried forward from the deleted Revision-1 context-loader.md so nothing was lost in the LLM-to-script move). Ref: T-243
Per-task loop (load context -> generate -> gate -> escalate-or-commit), the four-check gate list carried forward from the deleted quality-gate-runner.md, its per-check report shape, and a fully specified DEFECT-### escalation identifier (fields, open/resolve lifecycle, recording location). Ref: T-244
Extends Stage 5's existing REQ -> ... -> TASK -> CHK -> CODE chain by filling the CODE leaf Stage 5 already reserved but never populated -- appended to the existing pipeline/05-plan/traceability.md, no parallel file. Explicitly references traceability-check.py's existing chain format rather than redefining one. Ref: T-245
Supported modes scoped to single-task + milestone-batch (module/ work-package/sprint/project explicitly deferred per AC-BUILDREF-001b), resume semantics, profile interaction, the parallel_build.py delegation path, failure handling, and completion report shape. Ref: T-246
Replaces the Revision-1 content (which orchestrated three sub-agent personas by sequential persona-adoption) with a thin router matching agents/planner-pro.md's shape: short Role/Goal, then a Reference Loading Protocol table naming references/build/01..05.md in order. Its own job is narrow -- generate code, generate tests, self-check against the spec -- using the context bundle scripts/build_executor.py (T-248) provides. Output Contract explicitly excludes committing, writing progress.md, and running the full gate chain. 111 lines; Reference Loading Protocol table names all five references/build/0N-*.md files in order (AC-BUILDAGENT-001a); Output Contract excludes committing/progress-write/full-gate-running (AC-BUILDAGENT-001b). Ref: T-247
…DCTX-002 Mid-build correction (user caught it): context-resolution was reading flat files (pipeline/04-spec/technical-spec.md, pipeline/03-architecture/architecture.md) copied over from the deleted Revision-1 context-loader.md, without checking whether that matches what the Pro-tier upstream stages actually produce. references/plan/ 01-foundation.md's own upstream-handoff list shows Stage 4 Pro's canonical output can be a read-doc.py-resolved split document set, not one flat file. Verified pipeline/05-plan/task-dag.md against references/stage-order.md (the authoritative, tier-agnostic mapping) and forge-sprint-pro's own usage -- that path was already correct, unlike references/plan/ 01-foundation.md's own "task-breakdown.md" naming (an isolated, unrelated drift in that doc, not touched here). Rewrote 02-context- resolution.md to resolve every canonical input via read-doc.py instead of a hardcoded flat-file assumption. Also captures new scope surfaced during the correction (REQ-BUILDCTX-002): context-resolution depth (spec_plan default / spec_arch_plan / full_chain) should be configurable, prompted once at Stage 5 entry, and persisted to pipeline/state.md -- plus a hard invariant, independent of depth, that a task with no requirement/spec citation fails context-resolution closed rather than building unbacked code. The Stage 5 prompt UX and the depth-widening logic are new tasks T-252/ T-253, explicitly sequenced after T-251 so they track the decision without blocking Phase 2's critical path, which ships fully working at the spec_plan default. Ref: T-243
Implements the Script-owns list from BUILDER_PRO-PLAN.md's Phase 2: context resolve (read-doc.py against the real canonical task-dag/spec base paths, spec_plan depth -- REQ-BUILDCTX-002's arch/full-chain widening is T-253), gate execution (four checks + profile additional_criteria, per-check report), commit + progress write only after every gate check passes, traceability update (extends pipeline/05-plan/traceability.md's CODE leaf per T-245), one build-log.jsonl line per attempt, DEFECT-### escalation on a second consecutive failure (not the first), resume (skip done tasks), and batch delegation to parallel_build.run_parallel_build. Also implements REQ-BUILDEXEC-001's hard requirement invariant: a task whose REQ-IDs don't resolve against pipeline/01-srs/srs.md fails context-resolution closed -- no bundle, no generation, nothing builds without a traceable requirement or specification. TDD red-first: 29 tests written and confirmed failing on ModuleNotFoundError before implementation existed, all green after. Full unit suite 1915 pass (was 1886 + 29 new, zero regressions). Covers: context-resolve scoping (AC-BUILDEXEC-001a), gate per-check reporting never one aggregate boolean (AC-BUILDEXEC-001b), batch path calls parallel_build.run_parallel_build rather than duplicating its logic (AC-BUILDEXEC-001c), traceability-chain extension after commit (AC-BUILDEXEC-001d), commit/progress-write-only-on-pass, build-log.jsonl append shape, and resume skip-logic. Ref: T-248
Replaces the Revision-1 draft (which orchestrated three sub-agent personas and never referenced a script) with one that actually invokes scripts/build_executor.py for context resolution and the gate/commit/ progress/traceability mechanics, and adopts agents/builder-pro.md for the generative step in between. Zero domain logic duplicated in the skill itself. Steps reference both scripts/build_executor.py and agents/builder-pro.md (AC-BUILDSKILL-001a). skills/forge-build/SKILL.md and agents/builder.md untouched. Ref: T-249
Replaces the Revision-1 version (asserted 3 sub-agent personas referenced in order) with one asserting the corrected architecture: forge-build-pro/SKILL.md references both scripts/build_executor.py and agents/builder-pro.md; builder-pro.md references all five references/build/0N-*.md files in order and does not reference the deleted Revision-1 sub-agents; skills/forge-build/SKILL.md and agents/builder.md stay byte-identical to the 6a22fa1 baseline (same regression guard as Revision 1, re-applied to the corrected file set). 13/13 pass against the T-247/T-248/T-249 output. Ref: T-250
… refs BUILDER_PRO-PLAN.md is an internal planning input for this repo's own build/ pipeline (like the brainstorm behind an SRS) -- it is not part of the plugin an end user installs. references/build/*.md ships to every user's project and gets loaded at runtime by agents/builder-pro.md; citing an external doc that only exists in forge-plugin's own dev repo made those citations meaningless (and misleading) outside this repo. Removed all 9 citations across the five files, keeping the substance -- rewrote each as a directly-stated architectural rule instead of an attributed quote, matching how references/plan/*.md and every other Stage 1-5 Pro reference set already reads (self-contained, no citation of whatever internal process produced it). Citations remain correctly in build/01-srs/srs-v0.8.0.md, build/04-plan/task-dag-v0.8.0.md, and build/05-implementation/progress.md -- those are this repo's own internal build-tracking documents, never shipped, and BUILDER_PRO-PLAN.md is exactly the right thing to cite there. agents/builder-pro.md, skills/forge-build-pro/SKILL.md, and scripts/build_executor.py were already clean (verified by grep -- zero citations in any shipped file after this commit). 42/42 wiring + executor tests still pass. Ref: T-242
…cutor.py Background security review flagged two issues in scripts/build_executor.py: 1. Argument injection: record_attempt() ran `git add *files` with no `--` pathspec separator. A generated file path starting with `-` would be interpreted as a git option instead of a path. Fixed by adding `--` before the pathspecs. 2. Fail-open state drift: consecutive_failures() silently `continue`d past a malformed build-log.jsonl line instead of accounting for it. Since this counter feeds the DEFECT-### escalation gate, silently skipping corrupted entries could undercount failures and suppress the safety check entirely on a corrupted log. Fixed to fail closed: a malformed line now counts as a failure (biasing toward escalation, not silent continuation) and logs a warning to stderr instead of swallowing the error silently. +3 regression tests. 32/32 build_executor tests pass; full unit suite 1931 pass, zero regressions. Ref: T-248
Full sweep: 1931 unit tests pass, validate-plugin.py exit 0, full-pipeline.sh 12/12 gates + traceability intact. agents/builder.md and skills/forge-build/SKILL.md re-verified byte-identical to the pre-T-235 6a22fa1 baseline. progress.md: v0.8.0 Revision 2 marked COMPLETE (T-241..T-251) with the full commit trail, both mid-build corrections, and the security-review fixes. Next: T-252/T-253 (REQ-BUILDCTX-002 follow-on), tracked but not blocking -- Phase 2 ships fully working at the spec_plan default. CHANGELOG.md [Unreleased]: replaced the Revision-1 entry (3 sub-agent personas) with the actual Phase 2 shape (script + thin agent split). lessons.md: two new entries from this session's corrections -- verifying a Pro-tier upstream artifact's real shape against stage-order.md rather than carrying a flat-file assumption forward from a deleted file, and keeping internal build-planning-doc citations confined to build/ rather than shipped plugin artifacts. Ref: T-251
PR #63's CI unit job failed: test_forge_build_skill_unchanged_from_pre_feature_baseline and test_builder_agent_unchanged_from_pre_feature_baseline both errored with `git show 6a22fa1:<path>` returning exit 128 ("bad object"). Root cause: .github/workflows/tests.yml's actions/checkout has no fetch-depth set, so it defaults to a shallow fetch-depth of 1 -- 6a22fa1 is a real ancestor of HEAD but its objects are never fetched in CI, even though the same command works locally with full history. This dependency on checkout depth was inherited from Revision 1's original version of this test (same git-show-against-a-fixed-sha technique) and was never actually exercised through GitHub Actions CI before now. Fix: compare against a literal fixture snapshot (tests/fixtures/pre_pro_tier_baseline/{forge-build-SKILL.md,builder.md}) instead of git history -- verified byte-identical to the 6a22fa1 objects before switching, so the invariant being checked is unchanged, only the mechanism. No history-depth dependency, works identically locally and in CI. 13/13 wiring tests pass; full unit suite 1931 pass. Ref: T-250
tonmoy007
pushed a commit
that referenced
this pull request
Aug 10, 2026
task-dag-v0.8.0.md: Follow-On section marked DONE with both commit refs. progress.md: v0.8.0 Revision 2 now spans T-241..T-253, nothing tracked and outstanding; also records the PR #63 CI fix (shallow checkout broke the git-show baseline test, fixed via literal fixture snapshot). CHANGELOG.md: Deferred note replaced with the shipped configurable-depth description. lessons.md: a git-history-dependent test can pass locally (full clone) and fail in CI (default actions/checkout is shallow, fetch-depth 1) on the exact same commit -- check workflow fetch-depth before writing a `git show <ancestor-sha>:path` assertion, prefer a fixture snapshot. Ref: T-253
3 tasks
tonmoy007
added a commit
that referenced
this pull request
Aug 10, 2026
…002) (#64) * feat(T-252): forge-plan-pro Stage 5 entry prompts + persists build_context_depth Adds scripts/set-context-depth.py -- validates the requested depth (spec_plan/spec_arch_plan/full_chain) and updates pipeline/state.md atomically via _state_lib, same read-modify-write pattern scripts/set-profile.py uses for project_type. Refuses to overwrite an already-set value unless --force is passed. Wires a new "Context Depth for Stage 6" section into skills/forge-plan-pro/SKILL.md's pre-flight: if build_context_depth is unset, ask the user once which depth Stage 6 Pro's context-resolution should use (spec_plan recommended default / spec_arch_plan / full_chain) and persist it; if already set, skip silently -- never re-prompt or overwrite an explicit prior choice (AC-BUILDCTX-002c). Does not block Stage 5 planning on the answer. +7 tests. Full unit suite 1938 pass, zero regressions. Ref: T-252 * feat(T-253): wire build_context_depth into build_executor.py's context-resolve Adds read_context_depth() (fail-soft: missing state.md, unset field, or an unrecognized value all default to spec_plan -- AC-BUILDCTX-002b) and widens resolve_context() at the two non-default depths: - spec_arch_plan: resolves pipeline/03-architecture/architecture via read-doc.py, scoped to the task's REQ-IDs/Files the same way spec excerpts already are. - full_chain: additionally resolves a new full_chain_excerpts dict -- PRD, user stories, user flows, and the highest-numbered pipeline/05-plan/sprints/sprint-NNN.md when one exists -- same task-scoped matching, informational only. The hard REQ-ID invariant and Output Contract are unchanged by depth. Updated references/build/02-context-resolution.md's Context Depth and Context Bundle sections to match the actual wiring (was previously "T-252/T-253, not yet wired"). TDD red-first: 11 new tests confirmed failing (AttributeError / NameError on the not-yet-existing depth machinery) before implementation, all green after. Full unit suite 1949 pass, zero regressions. Ref: T-253 * docs(T-252,T-253): mark REQ-BUILDCTX-002 follow-on complete task-dag-v0.8.0.md: Follow-On section marked DONE with both commit refs. progress.md: v0.8.0 Revision 2 now spans T-241..T-253, nothing tracked and outstanding; also records the PR #63 CI fix (shallow checkout broke the git-show baseline test, fixed via literal fixture snapshot). CHANGELOG.md: Deferred note replaced with the shipped configurable-depth description. lessons.md: a git-history-dependent test can pass locally (full clone) and fail in CI (default actions/checkout is shallow, fetch-depth 1) on the exact same commit -- check workflow fetch-depth before writing a `git show <ancestor-sha>:path` assertion, prefer a fixture snapshot. Ref: T-253 --------- Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
tonmoy007
added a commit
that referenced
this pull request
Aug 10, 2026
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
* refactor(pro-tier): normalize Stage 1-3 Pro agents to thin-router pattern (#61)
* (resolve) merge conflict (#60)
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* refactor(pro-tier): normalize Stage 1-3 Pro agents to thin-router pattern
Stages 1-3 (SRS, Product, Architect) carried their full domain logic
inline in the agent/skill files, unlike Stages 4/5/sprint which already
follow a proven thin-router shape: a ~130-line agent that points at five
numbered reference docs, with the orchestration skill doing gating/state
only. Bring the remaining stages in line so every Pro-tier stage loads
and behaves the same way.
- agents/requirements-analyst-pro.md: 616 -> 81 lines; domain content
moved to references/srs/01-05.md
- agents/product-designer-pro.md: 347 -> 122 lines; domain content moved
to references/product/01-05.md; skills/forge-product-pro/SKILL.md lost
its inline Step 1-16 workflow duplication and Behavioral Rules section
- agents/system-architect-pro.md: 371 -> 129 lines; skills/forge-arch-pro/SKILL.md:
555 -> 222 lines. references/architect/{artifact-specs,identifiers-traceability,
validation-rules,workflow-steps}.md renumbered into 01-05.md, folding in
content that only existed in the skill's inline Phase 1/2 duplication
(Profile Extensions, an API-ownership fail condition, a 13th quality gate)
Verified with the fingerprint-diff method from the sprint-plan refactor
(PR #56): every flagged "missing" block was reformatting, not lost
content. No classic (non-pro) agent/skill touched.
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* Implement Stage 6 Builder Pro plan , srs-v0.8.0 (#63)
* (resolve) merge conflict (#60)
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* refactor/phase1-thin-router-stages-1-3 (#62)
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
* refactor(pro-tier): normalize Stage 1-3 Pro agents to thin-router pattern (#61)
* (resolve) merge conflict (#60)
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are e…
tonmoy007
added a commit
that referenced
this pull request
Aug 10, 2026
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
* refactor(pro-tier): normalize Stage 1-3 Pro agents to thin-router pattern (#61)
* (resolve) merge conflict (#60)
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* refactor(pro-tier): normalize Stage 1-3 Pro agents to thin-router pattern
Stages 1-3 (SRS, Product, Architect) carried their full domain logic
inline in the agent/skill files, unlike Stages 4/5/sprint which already
follow a proven thin-router shape: a ~130-line agent that points at five
numbered reference docs, with the orchestration skill doing gating/state
only. Bring the remaining stages in line so every Pro-tier stage loads
and behaves the same way.
- agents/requirements-analyst-pro.md: 616 -> 81 lines; domain content
moved to references/srs/01-05.md
- agents/product-designer-pro.md: 347 -> 122 lines; domain content moved
to references/product/01-05.md; skills/forge-product-pro/SKILL.md lost
its inline Step 1-16 workflow duplication and Behavioral Rules section
- agents/system-architect-pro.md: 371 -> 129 lines; skills/forge-arch-pro/SKILL.md:
555 -> 222 lines. references/architect/{artifact-specs,identifiers-traceability,
validation-rules,workflow-steps}.md renumbered into 01-05.md, folding in
content that only existed in the skill's inline Phase 1/2 duplication
(Profile Extensions, an API-ownership fail condition, a 13th quality gate)
Verified with the fingerprint-diff method from the sprint-plan refactor
(PR #56): every flagged "missing" block was reformatting, not lost
content. No classic (non-pro) agent/skill touched.
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* Implement Stage 6 Builder Pro plan , srs-v0.8.0 (#63)
* (resolve) merge conflict (#60)
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* refactor/phase1-thin-router-stages-1-3 (#62)
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container execution
and Dockerfile/CI generation are explicitly out of scope.
Design brainstormed and approved 2026-06-24. Planning docs only — no code yet.
Ref: T-227..T-234
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat: add OpenCode plugin port
Port Forge from Claude Code to OpenCode plugin API.
- plugin.js event router (7 OpenCode events → Python hooks)
- opencode.jsonc manifest
- 34 skills, 18 agents, 71 scripts, 18 hooks copied
- Env var bridge: FORGE_ROOT replaces CLAUDE_PLUGIN_ROOT
- Tested: all 13 integration tests pass
* fix(opencode): repair lesson-writing CLI contract in stop-reflect.py
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written under this port. Fixes:
- extract-lessons.py gains --propose, which emits extracted lessons as YAML to
stdout instead of writing the file directly, matching the validate-then-write
contract stop-reflect.py's _parse_lesson_output already expected.
- stop-reflect.py's call site now passes --cwd/--input/--propose (the CLI that
actually exists) and pins cwd= on the subprocess, since plugin.js's spawn()
never sets one and the ambient process cwd isn't guaranteed to be the project
root under OpenCode.
Verified end-to-end: a correction flag now produces both tasks/lessons.md and
.forge/lessons.yaml entries.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(opencode): add pipeline orchestrator agent and traceability validation skill
Two OpenCode-only additions (agents/orchestrator.md is deliberately not mirrored
to the root Claude Code plugin — the gap it closes is OpenCode-specific):
- agents/orchestrator.md + skills/forge-orchestrate: a dedicated persona that
drives the full 12-stage pipeline by adopting each stage's own skill in turn.
It exists because OpenCode's session.idle payload never carries a
transcript_path (no OpenCode event exposes one), so stop-reflect.py's
automatic done-signal detection is permanently False here — there was no
reliable path left to a per-stage state.md advance. This agent owns that
explicitly: it runs state-manager.py advance after every passing gate and
re-reads state.md to confirm the write landed before reporting a stage done,
rather than assuming state-manager.py's exit code was sufficient proof.
- scripts/validate-traceability.py + skills/forge-validate: a gap-analysis
report covering four checks the per-stage gate scripts don't do — malformed
IDs (wrong case/separator/digit-padding against the REQ-\d{3}/NFR-\d{3}
convention), misplaced ID definitions (a REQ/NFR/FEAT/UF heading defined
outside its home doc), duplicate ID definitions (same id heading-defined
twice in one file), and unimplemented/orphaned requirements (defined but
never referenced downstream) — folded together with a rollup of the existing
traceability-check.py and gate-completeness scripts so traceability is
confirmed end-to-end in one report.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add validate-traceability.py + shared _trace_scan.py module
Ports the OpenCode port's pipeline gap-analysis tooling to the root Claude Code
plugin, extracting the ID-scanning logic into a shared scripts/_trace_scan.py
module along the way (both trees now import the same implementation instead of
carrying two literal copies):
- scripts/_trace_scan.py: malformed/misplaced/duplicate/unimplemented ID checks,
plus find_matrix_cells() and attribute()/stage_for_path() — new helpers that
resolve a gap to the (stage, agent) responsible for it via _stage_table.py,
used by the traceability-matrix agent added in a later commit.
- scripts/validate-traceability.py (root, new) + skills/forge-validate/: the
same gap-analysis report already shipped in forge-opencode/, now available on
Claude Code too.
- forge-opencode/scripts/validate-traceability.py refactored to import from
_trace_scan.py — behavior-preserving; the existing opencode test suite passes
unchanged against the refactor.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* fix(root): port lesson-writing CLI contract fix from OpenCode port
hooks/stop-reflect.py called extract-lessons.py with --transcript/--since-flag,
neither of which extract-lessons.py's argparse ever defined — every invocation
failed with an argparse usage error (exit 2), so tasks/lessons.md and
.forge/lessons.yaml were never written. Same bug, same fix as the forge-opencode/
port (PR #50): extract-lessons.py gains --propose (emits YAML to stdout instead
of writing directly), and stop-reflect.py's call site uses the CLI that actually
exists (--cwd/--input/--propose, with cwd= pinned on the subprocess). Root and
forge-opencode/ are back in parity for these two files.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat(root): add pipeline orchestrator agent, adapted from OpenCode port
Ports agents/orchestrator.md + skills/forge-orchestrate/ (shipped OpenCode-only
in PR #50) to the root Claude Code plugin, with the rationale rewritten for this
platform: Claude Code's transcript-based auto-advance actually works here, so
the OpenCode-specific "no done signal" framing doesn't apply. The honest,
platform-neutral value-add does: no driver in the system — not even autopilot's
own "Advance" step (state-manager.py advance + autopilot.py record) — re-reads
state.md afterward to confirm the write landed; it trusts the exit code. This
agent's one job is treating that as a checked postcondition, every stage, on
both platforms. Positioned as a lighter, single-purpose complement to
/forge:autopilot (which remains the right tool for self-heal, background
dispatch, and context-window checkpointing), not a replacement for it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* feat: add traceability-matrix agent — ID x stage matrix with gap attribution
New cross-stage agent (agents/traceability-matrix.md) and skill
(/forge:trace-matrix, both trees) that generates the full pipeline traceability
matrix and attributes every gap to the specific stage agent responsible for it —
not the stage that originally defined the id, but the earliest downstream stage
that should have carried it forward and didn't (built on _trace_scan.attribute(),
which resolves this via references/stage-order.md).
scripts/trace-matrix.py writes two artifacts:
- pipeline/traceability-matrix.md — the id x stage matrix (define vs reference)
- .forge/traceability-gaps.jsonl — a fresh snapshot (overwritten, not appended)
of open gaps keyed by responsible agent
hooks/session-start.py (both trees) gains _traceability_gap_note(), following the
existing _health_surface_note/_unread_findings_note pattern: reads the jsonl
snapshot, surfaces an advisory note only to the agent whose stage is currently
active, and stays silent otherwise. Read-only, fail-soft, never blocking.
Fixed a self-referential bug found by the test suite: pipeline/
traceability-matrix.md is written back into the same pipeline/ tree the scanner
sweeps, so a gap table quoting a malformed id (e.g. "req-001" in its own Detail
column) was being re-detected as a fresh instance on the next run. _trace_scan.py's
pipeline_md_files() now excludes known generated-report filenames from the scan.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* docs: document orchestrator, validate, and trace-matrix additions
README.md (root): new "Orchestrator" and "Traceability matrix & gap attribution"
subsections under Beyond the pipeline, plus command-reference rows for
/forge:orchestrate, /forge:validate, /forge:trace-matrix.
forge-opencode/README.md + CLAUDE.md: /forge:trace-matrix usage line and a new
"Traceability Matrix & Gap Attribution" section; the Scripts section is rewritten
to reflect that extract-lessons.py/validate-traceability.py are no longer
intentionally diverged from root — both trees were brought back into parity by
the preceding commits.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* UPDATE OPENCODE PLUGIN AGENT TOOLS
* (update) UPDATE THE SRS SKILL AND AGENT WORKFLOW
* fix(srs): restore traceability markers dropped in SRS rewrite (#53)
The requirements-analyst.md/forge-srs SKILL.md rewrite reworded the
clarification and web-research rules, losing the exact REQ-ID tags and
phrases (REQ-INTERACTIVE-CLARIFY-001, "Cite or skip", "before writing
srs.md", "unanswered") that T-121/T-126 tests assert on. Behavior was
unchanged; only the literal markers were gone.
Ref: T-121, T-126
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* refactor(agents): compact agent doc files (#54)
Beautify and compact 3 agent/skill doc files:
- agents/product-designer-pro.md: 1029→190 lines (82% reduction)
- agents/requirements-analyst.md: 438→200 lines (54% reduction)
- skills/forge-product/SKILL-pro.md: 748→210 lines (72% reduction)
Removed redundant whitespace, collapsed single-item lists,
deduplicated repeated content (validation rules, artifact listings,
pre-flight sections), while preserving all content, IDs, and rules.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* add(prompts)\n addeed new prompt for referencing pro upgradation
* feat(sprint): enterprise-grade Sprint Planner Pro agent + skill (#55)
* (update) agents and pro skills
* (update) agents and pro skills stage 1 and stage 4
* feat(plan): add reference-driven stage 5 planning
* (update) agents and pro skills stage 4 ,refector and breakdown into references
* feat(sprint): add enterprise-grade Sprint Planner Pro agent + skill
Adds an optional Sprint Planning & Execution layer aligned with the
redesigned Stage 5 Pro (planner-pro / forge-plan-pro): converts approved
pipeline/05-implementation-plan/ artifacts into deterministic,
capacity-bounded, traceable sprint backlogs (SPR-* records).
Purely additive — the legacy forge-sprint skill, scripts/sprint.py, and
their pipeline/05-plan/ output are untouched, so existing projects keep
working exactly as before. Sprint Planning is not a pipeline stage: it
never advances or mutates pipeline/state.md.
New files only:
- agents/sprint-planner-pro.md
- skills/forge-sprint-pro/SKILL.md
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* refactor(sprint): split Sprint Planner Pro into references/sprint-plan/ (#56)
Mirrors the planner-pro / spec-writer-pro pattern: agents/sprint-planner-pro.md
becomes a thin router (Role, Primary Goal, Reference Loading Protocol, short
pointer sections, Required Controls, Downstream Readiness) and the full
section-wise instructions move into five reference docs:
- references/sprint-plan/01-foundation.md (role, ownership, scope,
principles, sprint goal rules, deliverables)
- references/sprint-plan/02-capacity-dependency.md (capacity model,
dependency analysis, definition of ready, parallel execution)
- references/sprint-plan/03-risk-allocation.md (risk register, AI/developer
allocation)
- references/sprint-plan/04-traceability-validation.md (append-only lineage,
validation, quality gates)
- references/sprint-plan/05-workflow-governance.md (workflow, sprint review +
retrospective sub-workflows, profile overrides, revision, web research,
behavioral rules, completion)
skills/forge-sprint-pro/SKILL.md now lists the five references as mandatory
agent instructions (matching forge-plan-pro/SKILL.md) and defers profile-
override semantics to the new Profile Overrides section instead of
duplicating them.
Verified line-for-line against the prior monolithic agent (fingerprint diff)
before commit: every instruction, rule, and workflow step carried over —
nothing dropped, only reorganized (plus one quality-gate list promoted to a
table and one omitted sentence on stage-boundary restored). No existing
sprint/plan file touched.
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* (update) agents and pro skills stage 05 reference modified to existing folder structure 05-plan
* update (builder plan) New pro builder plan saved
* fix(agents, skills): restore behavioral requirement markers in SRS pipeline
Commit 147c930 stripped REQ-INTERACTIVE-CLARIFY-001 and REQ-WEBSEARCH-001
markers from agents/requirements-analyst.md and removed REQ-INTERACTIVE-CLARIFY-001
from skills/forge-srs/SKILL.md, causing test failures.
Restored:
- In requirements-analyst.md: "Clarification Strategy" section with explicit
single-bounded-round and "not a drip" language, plus "Web Research" section
with cite-or-skip rule.
- In forge-srs/SKILL.md: REQ-INTERACTIVE-CLARIFY-001 marker with clarification
timing and assumptions recording instruction.
All 6 failing tests now pass. No regressions.
Ref: fix/srs-marker-regression
---------
Co-authored-by: tonmoy <tonmoy@polygontech.xyz>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* (merge) conflict resolve
* resolve(conflict)UPDATE WITH MAIN AND MET MERGE CONFLICT
* refactor(pro-tier): normalize Stage 1-3 Pro agents to thin-router pattern (#61)
* (resolve) merge conflict (#60)
* fix(ci): remove literal ${{ }} from release.yml run-block comment
PR #46's comment wrote a literal empty GitHub expression `${{ }}` inside the
"Create tag and GitHub release" run block. GitHub scans the entire run script
(comments included) for template expressions, so the empty one fails to parse —
`workflow_dispatch` returned HTTP 422 "An expression was expected" (Line 61).
Rephrase the comment to describe the env-var pattern without writing a literal
expression, and add a note so it isn't reintroduced. No behavior change to the
release step. (v0.6.1 was tagged via a direct tag push, which worked in this
environment; this restores the server-side dispatch fallback for when it 403s.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix: restore SRS behavioral requirement markers (#57)
* Feat/opencode port (#52)
* docs(plan): add v0.7.0 SRS + task-DAG — Docker workflow enforcement + tooling preflight
Author the planning docs for v0.7.0 (T-227..T-234): a fail-soft, never-block
Docker + tooling layer.
- Cross-cutting Docker hygiene: an advisory check_docker_readiness.py (no-op
without Docker artifacts, exits 0 even with findings) surfaced at the deploy
stage for any project, profile or not.
- Extensible tool registry + tool_preflight.py: detect missing docker / docker
compose / gh (shutil.which + cached .forge/tool-status.json + 24h TTL),
offer-install in a new /forge:preflight skill after explicit confirmation —
never auto-run, never block.
- Opt-in `docker` profile (suggested, never auto-assigned over api/fullstack)
with deploy/architecture emphasis + the advisory hygiene criterion.
Docker is orthogonal to the mutually-exclusive profile cascade, so handling is
cross-cutting rather than a 9th cascade profile. Sandboxed container exec…
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
. Derived from docs/builder-pro-plan-analysis.md (analysis of BUILDER_PRO-PLAN.md, verdict: “sound vision, scope needs trimming, execute Phase 1 only”). This SRS formalizes only the Recommended Execution Plan from that analysis — nothing from the original 17-task / 13-sub-agent proposal beyond that trimmed scope.