Code Forge — Review

Review the code quality of a feature's implementation against its plan, checking code quality, test coverage, security, and consistency.

When to Use

•Feature implementation is complete or nearly complete
•Want to verify code quality before creating a PR
•Need a structured review against the original plan

Workflow

code

Locate Feature → Collect Changes → Multi-Dimension Review (sub-agent) → Generate Report → Update State → Summary

Context Management

The review analysis is offloaded to a sub-agent to handle large diffs without exhausting the main context.

Detailed Steps

Step 0: Configuration Detection and Loading

Important: Detect and load configuration before any operation.

0.1 Detect Project Root

Search upward for project root markers:

code

.git/ | .code-forge.json | pyproject.toml | package.json | Cargo.toml | go.mod | build.gradle | pom.xml | Makefile

If no root is found, use the current directory as the project root.

0.2 Load Configuration (three-layer merge)

Load configuration by priority (each layer deep-merges into previous):

•
System defaults:
- •_tool.name = "code-forge" (read-only, not overridable)
- •_tool.description = "Transform documentation into actionable development plans with task breakdown and status tracking" (read-only)
- •_tool.url = "https://github.com/tercel/code-forge" (read-only)
- •_tool.skills_collection = "https://github.com/tercel/claude-code-skills" (read-only)
- •directories.base = "planning/", directories.input = "features/", directories.output = "implementation/"
- •git.auto_commit = false, git.commit_state_file = true, git.gitignore_patterns = []
- •execution.default_mode = "ask", execution.auto_tdd = true, execution.task_granularity = "medium"
•
User global config (~/.code-forge.json, if exists) → deep-merge into defaults
•
Project config (<project_root>/.code-forge.json, if exists) → deep-merge (highest priority)

0.3-0.6 Validate, Show Summary, Store Context

Same as other skills — validate config, display summary, store resolved paths. Proceed directly.

Step 1: Locate Feature

1.1 With Feature Name Argument

If the user provided a feature name (e.g., /code-forge:review user-auth):

•Look for {output_dir}/{feature_name}/state.json
•If not found: show error, list available features

1.2 Without Argument

If no feature name:

•Scan {output_dir}/*/state.json for all features
•Filter to features with at least one "completed" task
•If none: "No features with completed tasks to review."
•If one: use it automatically
•If multiple: use AskUserQuestion to let user select

1.3 Load Feature Context

•Read state.json
•Read plan.md (for acceptance criteria and architecture)
•Note completed task count and overall progress

Step 2: Collect Change Scope

2.1 From Commits

Extract all commit hashes from state.json → tasks[].commits:

•Flatten all commit arrays into a single list
•If commits are recorded, use git diff between the earliest and latest commits
•If no commits recorded, fall back to scanning files involved in tasks

2.2 From Task Files

Read all tasks/*.md files and collect their "Files Involved" sections:

•Build a complete list of files created/modified by this feature
•Read current state of each file

2.3 Summary

Store:

•Total files changed
•Total lines added/removed (from git diff)
•List of all affected files

Step 3: Multi-Dimension Review (via Sub-agent)

Offload to sub-agent to handle the full diff analysis.

Spawn a Task tool call with:

•subagent_type: "general-purpose"
•description: "Review feature: {feature_name}"

Sub-agent prompt must include:

•Feature name and plan.md file path
•List of all affected files (sub-agent reads them)
•The acceptance criteria from plan.md
•Instructions to review across all dimensions below

Review dimensions:

3.1 Code Quality

•Naming conventions: consistent, descriptive, follows project style
•Code structure: appropriate abstractions, no unnecessary complexity
•DRY: no duplicated logic
•Error handling: appropriate error handling at boundaries
•Comments: only where logic isn't self-evident

3.2 Test Coverage

•Every task has corresponding tests
•Tests cover happy path, edge cases, and error cases
•Tests are independent and deterministic
•Test names describe the behavior being tested

3.3 Security

•OWASP top 10 check: SQL injection, XSS, CSRF, etc.
•No hardcoded secrets or credentials
•Input validation at system boundaries
•Proper authentication/authorization checks

3.4 Plan Consistency

•All acceptance criteria from plan.md are met
•Architecture matches the design in plan.md
•No unplanned features added (scope creep)
•All planned tasks are implemented

Sub-agent must return:

code

REVIEW_SUMMARY:
  overall_rating: <pass | pass_with_notes | needs_changes>
  total_issues: <number>

CODE_QUALITY:
  rating: <good | acceptable | needs_work>
  issues:
  - severity: <critical | warning | suggestion>
    file: path/to/file.ext
    line: <number or range>
    description: <what's wrong>
    suggestion: <how to fix>

TEST_COVERAGE:
  rating: <good | acceptable | needs_work>
  coverage_gaps:
  - <description of untested scenario>

SECURITY:
  rating: <pass | warning | critical>
  issues:
  - <description of security concern>

PLAN_CONSISTENCY:
  criteria_met: <X/Y>
  unmet_criteria:
  - <criterion not met>
  scope_issues:
  - <unplanned additions or missing planned features>

Step 4: Generate Review Report

Write review report to {output_dir}/{feature_name}/review.md:

markdown

# Code Review: {feature_name}

**Date:** {ISO date}
**Reviewer:** code-forge
**Overall Rating:** {pass | pass_with_notes | needs_changes}

## Summary

{1-2 paragraph summary of the review findings}

## Code Quality

**Rating:** {rating}

{issues table or "No issues found"}

## Test Coverage

**Rating:** {rating}

{coverage gaps or "All scenarios covered"}

## Security

**Rating:** {rating}

{security issues or "No security concerns"}

## Plan Consistency

**Criteria Met:** {X/Y}

{unmet criteria or "All criteria met"}

## Recommendations

{prioritized list of changes to make}

## Verdict

{final assessment and recommendation: merge, fix then merge, or rework}

Step 5: Update state.json

•Read state.json

•Add or update review field in metadata:

json

{
  "review": {
    "date": "ISO timestamp",
    "rating": "pass_with_notes",
    "total_issues": 3,
    "report": "review.md"
  }
}

•Update state.json updated timestamp

Step 6: Summary and Next Steps

Display:

code

Code Review Complete: {feature_name}

Rating: {overall_rating}
Issues: {total_issues} ({critical} critical, {warning} warnings, {suggestion} suggestions)
Report: {output_dir}/{feature_name}/review.md

{If needs_changes:}
Recommended actions:
  1. {highest priority fix}
  2. {next priority fix}
  ...
  After fixing: /code-forge:review {feature_name}   Re-run review

{If pass or pass_with_notes:}
Ready for next steps:
  /code-forge:status {feature_name}         View final status
  Create a Pull Request