forge-next 0.1.1__py3-none-any.whl

forge_codex/__init__.py

@@ -0,0 +1,7 @@
+"""Forge Codex launcher package.
+
+This package provides the `forge` CLI entrypoint and bundles prompt/template
+assets so workflows can run against any target repo without vendoring the
+forge-codex repository into that repo.
+"""
+

forge_codex/assets/__init__.py

@@ -0,0 +1,2 @@
+"""Bundled runtime assets (prompts/templates)."""
+

forge_codex/assets/prompts/__init__.py

@@ -0,0 +1,2 @@
+"""Bundled prompt templates."""
+

forge_codex/assets/prompts/code-review/architecture_check.md

@@ -0,0 +1,78 @@
+# Phase 3: Team Dispatch — Architecture Mode
+
+Dispatch all reviewers to analyze design patterns, coupling, and SOLID principles.
+
+## Review Target
+
+**Mode:** Architecture Review
+**Target:** {{TARGET}}
+**Quick mode:** {{QUICK_MODE}}
+
+## Team Assignments
+
+{{TEAM_ASSIGNMENTS}}
+
+## Instructions
+
+### 1. Identify Scope
+
+Read the target files/modules and build a mental model of:
+- Module boundaries and public interfaces
+- Dependency graph (what depends on what)
+- Data flow patterns (how data moves through the system)
+- Error propagation patterns
+
+### 2. Dispatch Reviewers in Parallel
+
+**Architect Review — SOLID Principles:**
+- **S** (Single Responsibility): Does each module/class have one reason to change?
+- **O** (Open/Closed): Can behavior be extended without modifying existing code?
+- **L** (Liskov Substitution): Are subtypes truly substitutable for their base types?
+- **I** (Interface Segregation): Are interfaces minimal and focused?
+- **D** (Dependency Inversion): Do modules depend on abstractions, not concretions?
+
+**Architect Review — Coupling & Cohesion:**
+- Afferent coupling (Ca): How many modules depend on this one?
+- Efferent coupling (Ce): How many modules does this one depend on?
+- Instability (I = Ce / (Ca + Ce)): Is this module stable or volatile?
+- Cohesion: Do the elements within each module belong together?
+
+**Security Reviewer — Architectural Security:**
+- Are trust boundaries clearly defined?
+- Is authentication/authorization centralized or scattered?
+- Are there privilege escalation paths?
+- Is sensitive data properly compartmentalized?
+
+**QA Reviewer — Testability:**
+- Can components be tested in isolation?
+- Are dependencies injectable?
+- Are there hidden dependencies (globals, singletons)?
+- Is the test infrastructure adequate for the architecture?
+
+**Critic — Design Smells & Code Smells:**
+- Run code smells assessment per `templates/code-smells.md`
+- Priority smells: God Class, Shotgun Surgery, Inappropriate Intimacy (critical); Feature Envy, Long Method, Divergent Change (warning)
+- For each smell: cite file:line, name the smell, state the consequence, recommend the specific refactoring
+- Check for Dependency Structure Matrix issues: cyclic dependencies between modules, layering violations, coupling clusters
+
+**Investigator — Dependency Analysis:**
+- Map the full dependency graph
+- Identify circular dependencies
+- Check for dependency inversions (concrete depends on concrete)
+- Evaluate third-party dependency health
+
+**Doc-writer — Architecture Documentation:**
+- Is the architecture documented?
+- Do module-level docs explain the "why" not just the "what"?
+- Are architectural decisions recorded (ADRs)?
+
+### 3. Compile Findings
+
+Collect all findings into a unified list with:
+- Finding ID (F1, F2, ...)
+- Source reviewer
+- Severity: critical / warning / suggestion
+- Title (one line)
+- Detail (explanation with specific code references)
+
+Record findings in state and proceed to deep dive.

forge_codex/assets/prompts/code-review/deep_dive.md

@@ -0,0 +1,42 @@
+# Phase 4: Deep Dive
+
+The Investigator follows up on critical findings from the team dispatch phase.
+
+## Current Findings
+
+{{FINDINGS}}
+
+## Your Task
+
+### 1. Identify Critical Findings
+
+From the findings above, select all findings with severity **critical** or **warning**
+that need deeper investigation. These typically include:
+- Security vulnerabilities that need proof-of-concept verification
+- Architectural issues that may have wider impact than initially noted
+- Logic errors that need call-chain tracing to confirm
+- Performance concerns that need measurement
+
+### 2. Investigator Deep Dive
+
+For each critical finding, the Investigator should:
+
+1. **Read the relevant code** — not just the flagged line, but the full context
+   (the function, the caller, the callee, the error handler)
+2. **Trace the data flow** — where does the input come from? Where does the output go?
+3. **Check for similar patterns** — is this a one-off issue or a pattern repeated elsewhere?
+4. **Assess blast radius** — if this finding is a real problem, what is the impact?
+5. **Verify or refute** — does the deeper investigation confirm or dismiss the finding?
+
+### 3. Update Findings
+
+For each investigated finding:
+- If confirmed: add detail with code references and impact assessment
+- If refuted: mark as dismissed with explanation
+- If escalated: upgrade severity with justification
+- If new findings discovered: add them to the list
+
+### 4. Summarize
+
+Produce an updated findings list ready for the discussion phase.
+Focus on actionable findings — things the author can and should fix.

forge_codex/assets/prompts/code-review/diff_analysis.md

@@ -0,0 +1,73 @@
+# Phase 3: Team Dispatch — PR Mode (Diff Analysis)
+
+Dispatch all reviewers to analyze the PR diff in parallel.
+
+## Review Target
+
+**Mode:** PR Review
+**Target:** {{TARGET}}
+**Quick mode:** {{QUICK_MODE}}
+
+## Team Assignments
+
+{{TEAM_ASSIGNMENTS}}
+
+## Instructions
+
+### 1. Fetch the Diff
+
+- If target is a PR number: `gh pr diff {{TARGET}}`
+- If target is a branch: `git diff main...{{TARGET}}`
+- If target is file paths: `git diff -- {{TARGET}}`
+- If from handoff: diff the files listed in the handoff
+
+### 2. Dispatch Reviewers in Parallel
+
+Each reviewer analyzes the diff from their perspective. For each reviewer, produce
+a findings list with severity (critical / warning / suggestion).
+
+**Architect Review:**
+- Is the change consistent with existing architecture?
+- Does it introduce unwanted coupling or layering violations?
+- Are interfaces clean and well-defined?
+- Is error handling consistent with project patterns?
+
+**Security Reviewer:**
+- Are there injection vulnerabilities (SQL, XSS, command)?
+- Is authentication/authorization properly handled?
+- Are secrets or credentials exposed?
+- Is input validation sufficient?
+- Are data flows safe (no PII leaks, proper sanitization)?
+
+**QA Reviewer:**
+- Are edge cases handled?
+- Is there sufficient test coverage for the changes?
+- Do existing tests still pass with these changes?
+- Are error paths tested?
+
+**Critic:**
+- What assumptions does this change make?
+- What could go wrong that the author did not consider?
+- Is there over-engineering or unnecessary complexity?
+- Are there simpler alternatives?
+
+**Investigator:**
+- What is the blast radius of these changes?
+- What other code depends on the changed interfaces?
+- Are there transitive effects through the dependency graph?
+
+**Doc-writer:**
+- Do public APIs have adequate documentation?
+- Are comments accurate and helpful (not redundant)?
+- Should README or changelog be updated?
+
+### 3. Compile Findings
+
+Collect all findings into a unified list with:
+- Finding ID (F1, F2, ...)
+- Source reviewer
+- Severity: critical / warning / suggestion
+- Title (one line)
+- Detail (explanation with file:line references)
+
+Record findings in state and proceed to deep dive.

forge_codex/assets/prompts/code-review/discussion.md

@@ -0,0 +1,48 @@
+# Phase 5: Discussion
+
+You have completed the analysis phases. Present your findings to the user for interactive review.
+
+## Review Mode: {{MODE}} ({{MODE_DISPLAY}})
+## Target: {{TARGET}}
+
+## Accumulated Findings
+
+{{FINDINGS}}
+
+## Your Task
+
+Present findings organized by severity:
+
+1. **Critical** — Issues that must be fixed before merging or proceeding
+2. **Warnings** — Issues that are concerning but may be acceptable with justification
+3. **Suggestions** — Improvements that would make the code better
+
+Include code references (file:line) and explain the "why" for each finding.
+
+### Per-Finding Triage
+
+For each **critical** or **warning** finding, ask the user directly how to
+handle it (per `templates/user-questions.md`).
+
+- Question: `How should we handle finding [ID] ([severity]): [title]?`
+- Options:
+  - `Fix now` — block the workflow until this is resolved
+  - `Defer` — create a follow-up issue and proceed
+  - `Dismiss` — document why this is not a real issue and continue
+  - `Drill in` — investigate deeper before deciding
+
+Record the user's decision in the finding tracker. "Drill in" re-enters the
+discussion for that finding with deeper analysis before re-asking.
+
+### Overall Progress
+
+After triaging the highest-severity findings, ask the user directly whether to
+continue or proceed to the report.
+
+- Question: `Done triaging findings?`
+- Options:
+  - `Proceed` — all important findings are handled, so write the report
+  - `More triage` — keep discussing remaining findings
+  - `Re-scan` — dispatch reviewers again with updated focus
+
+When the user chooses "Proceed", advance to the next phase.

forge_codex/assets/prompts/code-review/mode_selection.md

@@ -0,0 +1,45 @@
+# Phase 2: Mode Selection
+
+Confirm and configure the review mode for this code review session.
+
+## Detected Configuration
+
+**Mode:** {{MODE}} ({{MODE_DISPLAY}})
+**Target:** {{TARGET}}
+**Quick mode:** {{QUICK_MODE}}
+
+## Mode Details
+
+### PR Mode (`pr`)
+Best for reviewing a specific PR or set of changes against a base branch.
+- Fetch the full diff
+- All reviewers analyze the diff from their perspective
+- Focus: correctness, style, test coverage, security
+
+### Deep Mode (`deep`)
+Best for troubleshooting reviews or investigating specific problem areas.
+- Trace code paths related to the issue
+- Focus on call chains, data flow, error handling
+- Security Reviewer traces auth and data boundaries
+- Investigator follows dependency chains
+
+### Architecture Mode (`architecture`)
+Best for reviewing design decisions, structural patterns, and system health.
+- Check SOLID principles adherence
+- Analyze coupling and cohesion metrics
+- Review dependency direction and layering
+- Evaluate extensibility and maintainability
+
+## Your Task
+
+1. **Confirm the mode** with the user (or auto-confirm if the mode is obvious)
+2. **Prepare mode-specific instructions** for each team member:
+
+{{TEAM_ASSIGNMENTS}}
+
+3. **Set the review scope:**
+   - For PR mode: identify the exact commits/diff to review
+   - For deep mode: identify the code paths to trace
+   - For architecture mode: identify the modules/packages to analyze
+
+4. Record the finalized mode and scope, then proceed to team dispatch.

forge_codex/assets/prompts/code-review/report.md

@@ -0,0 +1,42 @@
+# Phase 6: Report
+
+Write the final code review report and hand off to the test skill.
+
+## Review Summary
+
+**Mode:** {{MODE}} ({{MODE_DISPLAY}})
+**Target:** {{TARGET}}
+**Quick mode:** {{QUICK_MODE}}
+
+## Final Findings
+
+{{FINDINGS}}
+
+## Your Task
+
+### 1. Write the Code Review Report
+
+Write the report to `.codex/forge-codex/memory/code-review-report.md` with this structure:
+
+- Summary section with mode, target, date, reviewers
+- Findings table: ID, Severity, Title, Status
+- Detailed findings: each with severity, source reviewer, file:line, detail, recommendation
+- High-level recommendations
+- Handoff notes for the test skill (areas needing test attention, edge cases found)
+
+### 2. Update Memory
+
+- Update `.codex/forge-codex/memory/project.md` with code review completion status
+- Record the finding count and severity breakdown
+
+### 3. Prepare Handoff
+
+The handoff file will be written automatically. Ensure the findings are
+recorded in the state so the test skill knows what to focus on.
+
+### 4. Present Dashboard
+
+Show the user:
+- Total findings by severity
+- Open vs dismissed vs resolved
+- Suggested next step: `test`

forge_codex/assets/prompts/code-review/security_scan.md

@@ -0,0 +1,76 @@
+# Phase 3: Team Dispatch — Deep Mode (Security & Troubleshooting Scan)
+
+Dispatch all reviewers to trace code paths and investigate specific areas.
+
+## Review Target
+
+**Mode:** Deep Troubleshooting Review
+**Target:** {{TARGET}}
+**Quick mode:** {{QUICK_MODE}}
+
+## Team Assignments
+
+{{TEAM_ASSIGNMENTS}}
+
+## Instructions
+
+### 1. Identify Investigation Areas
+
+From the target and handoff context, identify:
+- Specific code paths that need tracing
+- Error conditions or failure modes to investigate
+- Security-sensitive paths (auth, data handling, external input)
+- Performance-critical paths
+
+### 2. Dispatch Reviewers in Parallel
+
+**Security Reviewer — Code Path Tracing:**
+- Trace all paths where external input enters the system
+- Follow data through validation, processing, storage, and output
+- Check for injection points at every boundary crossing
+- Verify authentication checks on every protected resource
+- Map authorization decision points and verify they are correct
+- Check for TOCTOU (time-of-check-time-of-use) vulnerabilities
+- Review cryptographic usage (algorithms, key management, random generation)
+
+**Investigator — Deep Code Path Analysis:**
+- Trace the specific code paths related to the target issue
+- Follow the call chain from entry point to data store and back
+- Map error propagation: where do errors originate and where are they caught?
+- Identify silent failure modes (swallowed exceptions, default values hiding errors)
+- Check for race conditions in concurrent code paths
+- Trace resource lifecycle (open/close, acquire/release)
+
+**Architect — Structural Analysis:**
+- Are the code paths well-structured and easy to follow?
+- Is error handling consistent across the traced paths?
+- Are there unnecessary indirections or overly complex control flow?
+- Do the code paths respect module boundaries?
+
+**QA Reviewer — Edge Case Analysis:**
+- What happens with empty/null/zero inputs on these paths?
+- What happens when external services are unavailable?
+- What happens under concurrent access?
+- What happens at boundary values (max int, empty string, huge payload)?
+
+**Critic — Assumption Audit:**
+- What assumptions do these code paths make?
+- Which assumptions are validated and which are implicit?
+- What happens when assumptions are violated?
+- Are there defensive checks where assumptions might fail?
+
+**Doc-writer — Documentation Gaps:**
+- Are complex code paths adequately commented?
+- Are error codes and failure modes documented?
+- Is the expected behavior documented for edge cases?
+
+### 3. Compile Findings
+
+Collect all findings into a unified list with:
+- Finding ID (F1, F2, ...)
+- Source reviewer
+- Severity: critical / warning / suggestion
+- Title (one line)
+- Detail (explanation with file:line references and code path traces)
+
+Record findings in state and proceed to deep dive.

forge_codex/assets/prompts/code-review/target_detection.md

@@ -0,0 +1,31 @@
+# Phase 1: Target Detection
+
+You are starting a code review. First, identify what will be reviewed.
+
+## Current Target
+
+**Target argument:** {{TARGET}}
+**Detected mode:** {{MODE}} ({{MODE_DISPLAY}})
+
+{{HANDOFF_CONTENT}}
+
+## Your Task
+
+1. **Identify the review target:**
+   - If a PR number was given, verify it exists with `gh pr view <number>`
+   - If a branch was given, verify it exists and check its diff against main
+   - If file paths were given, verify they exist
+   - If a handoff from implement exists, extract the changed files list
+   - If nothing was provided, check git for uncommitted changes or recent commits
+
+2. **Gather context:**
+   - Read `.codex/forge-codex/memory/project.md` if it exists for project context
+   - Check for recent handoff files to understand flow position
+   - Note the scope: how many files, how many lines changed
+
+3. **Confirm with user:**
+   - Present the detected target and mode
+   - Ask if they want to adjust the mode or target
+   - If quick mode: note that only lead reviewers (Architect, QA) will participate
+
+Record the confirmed target in the state and proceed to mode selection.

forge_codex/assets/prompts/develop/approval.md

@@ -0,0 +1,30 @@
+# Stage 3 — Solution Review & User Approval
+
+## Review Loop
+Per `templates/review-loop.md`:
+| Step | Agent | Focus |
+|------|-------|-------|
+| Self-review | Architect | Honest cons? Consistent scores? |
+| Cross-review | Security Reviewer + QA | Security implications? Testability? |
+| Critic challenge | Critic | Worst-case outcome? Understated risks? |
+| PM validation | PM | Enough info for user to choose? |
+| Pre-mortem | All agents | Imagine this solution failed — what happened? |
+
+Before presenting to the user, run a pre-mortem per `templates/pre-mortem.md`. Each agent generates 2-3 failure scenarios. Categorize, prioritize, and add mitigations to the risk assessment. Record any findings that change the recommendation.
+
+## User Approval
+
+Present scored solutions summary:
+{{SOLUTIONS_SUMMARY}}
+
+Then ask the user directly for approval (per `templates/user-questions.md`).
+Use this question and these options:
+
+- Question: `Approve the recommended solution for implementation?`
+- Options:
+  - `Approve` — accept the recommendation and hand off to `plan`
+  - `Revise` — return to Stage 2 with feedback
+  - `Alternate` — pick a different scored alternative
+  - `Reject` — stop here because no solution is acceptable
+
+Record the user's decision in `project.md` and branch accordingly.

forge_codex/assets/prompts/develop/handoff.md

@@ -0,0 +1,21 @@
+# Develop Complete — Handoff
+
+## Handoff
+Write `.codex/forge-codex/memory/handoff-develop.md` with:
+- Approved solutions with beads IDs
+- Team composition
+- Scope assessment
+- Task type
+- Key investigation findings
+
+## Dashboard
+Render skill completion dashboard per `templates/dashboard.md`.
+
+## Doc-writer Capture
+Dispatch Doc-writer to capture learnings in `.codex/forge-codex/memory/doc-writer.md`.
+
+## Suggested Next
+`plan`
+
+## Git Checkpoint
+git add .codex/forge-codex/ && git commit -m "workflow: develop complete -- solutions approved"

forge_codex/assets/prompts/develop/investigation.md

@@ -0,0 +1,25 @@
+# Stage 1 — Investigation
+
+Dispatch agents for deep investigation.
+
+## Agent Dispatch
+
+### Investigator (evidence gathering)
+Explore the codebase and gather evidence:
+- Read relevant code paths end-to-end
+- Run existing tests, collect results
+- Check git history for recent changes
+- Collect error messages, stack traces, reproduction steps
+- For bugfixes: follow `templates/systematic-debugging.md`
+
+Write evidence to `.codex/forge-codex/memory/investigator.md`
+
+### Architect (analysis lead)
+Analyze the evidence using `templates/five-why-protocol.md`:
+- For each issue/challenge, drill through up to 5 why-layers
+- Pattern analysis and hypothesis testing at each layer
+- Record evidence at every layer
+- Stop at an actionable root cause
+- For features: use `templates/brainstorming.md` for requirements exploration
+
+Write findings to `.codex/forge-codex/memory/investigation.md`

forge_codex/assets/prompts/develop/investigation_review.md

@@ -0,0 +1,14 @@
+# Investigation Review Loop
+
+Per `templates/review-loop.md`:
+
+| Step | Agent | Focus |
+|------|-------|-------|
+| Self-review | Architect | Did I stop too early? Did I validate every hypothesis? |
+| Cross-review | QA Reviewer | Are findings reproducible? Evidence concrete? Coverage gaps? |
+| Critic challenge | Critic | What assumptions are untested? What if the opposite is true? |
+| PM validation | PM | Complete against task type checklist? Beads IDs present? |
+
+{{REVIEW_STATE}}
+
+Loop until all four pass cleanly in the same round.

forge_codex/assets/prompts/develop/scope.md

@@ -0,0 +1,38 @@
+# Scope Assessment & Team Composition
+
+## Scope
+
+First, infer task type and layers from the user's initial description. If
+anything is unclear, ask the user directly to confirm (per
+`templates/user-questions.md`).
+
+- Question 1: `What type of task is this?`
+  - `Feature` — new functionality or enhancement
+  - `Bugfix` — fix broken behavior
+  - `Refactor` — improve structure without changing behavior
+- Question 2: `Which layers does this task touch?`
+  - `Frontend` — UI or client-side changes
+  - `Backend` — API or server-side changes
+  - `Infra` — infrastructure, CI/CD, or deploy
+  - `Something else` — let the user specify manually
+
+### Complexity
+
+Estimate automatically from scope:
+- Small (1-2 files)
+- Medium (3-10 files)
+- Large (10+ files)
+
+## Team Composition
+
+Base roles for every task: **Architect, Investigator, QA, Critic, Doc-writer.**
+
+**Security activation rule:** Add the Security role whenever *any* selected layer includes Backend or Infra, or when auth/data-integrity concerns are present regardless of layer.
+
+| Task Type | Additional Roles |
+|-----------|-----------------|
+| Feature | +Security (if Backend or Infra selected) |
+| Bugfix | +Security (if auth/data) |
+| Refactor | +Security (if auth/data) |
+
+Record team composition in project.md.