From aiforging
Use when /aiforging:setup has confirmed a backend or fullstack project and needs a non-destructive, advisory audit of how closely that project's current structure aligns with the AI Forging architectural ideals. Produces a structured ANALYSIS.md report with a score, findings, and severities. Never modifies files.
How this skill is triggered — by the user, by Claude, or both
Slash command
/aiforging:architecture-analyzerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Read a target project's current shape and compare it against the AI Forging architectural ideals documented in `${CLAUDE_PLUGIN_ROOT}/conventions/architecture/` and `${CLAUDE_PLUGIN_ROOT}/conventions/tdd/`. Produce a clear, honest report the user can act on.
Read a target project's current shape and compare it against the AI Forging architectural ideals documented in ${CLAUDE_PLUGIN_ROOT}/conventions/architecture/ and ${CLAUDE_PLUGIN_ROOT}/conventions/tdd/. Produce a clear, honest report the user can act on.
This skill is read-only. It never creates, edits, deletes, or moves files in the target project. If a user asks the skill to "fix" what it found, refer them to /aiforging:execute-plan (which is deferred for v0.1.0) or to manual refactoring with the pattern library.
/aiforging:setup Step 5 against each confirmed backend or fullstack project.scripts/detect-project.py, if already available. If not, the skill runs the detector first.Write the report to <target>/.aiforging/ANALYSIS.md. Also return a concise top-line summary (score + top 3 findings) to the caller for inline display.
The report has this shape:
# AI Forging Architecture Analysis
**Project:** <name>
**Path:** <abs path>
**Stack:** <detected stack, e.g., symfony-php + doctrine + phpunit>
**Analyzed:** <ISO date>
**Score:** <0-10>
## Summary
<2-3 sentences on the overall shape. What's healthy, what's not.>
## Findings
<One section per finding, ordered by severity (critical → high → medium → low → info).>
### [<severity>] <Finding title>
**What we saw:**
<Concrete evidence with file paths and line numbers or quoted snippets.>
**Why it matters:**
<One paragraph referencing the relevant AI Forging convention doc.>
**How to fix it:**
<High-level refactor direction. Do NOT write patch/code.>
**Related conventions:**
- `conventions/architecture/<relevant-doc>.md`
- `conventions/refactoring/anti-patterns/<relevant>.md`
## Checklist
<Yes/No table of the capability contract items, see below.>
## Next
The proposed plan for remediation will be written to
`<target>/.aiforging/PROPOSED_PLAN.md` by `/aiforging:setup` Step 6.
For each dimension, collect evidence, determine a rating (healthy / mixed / poor / absent), and translate the rating into findings with severities.
src/ (or stack-equivalent) tree. Do you see Domain/Feature/Subfeature/Layer or something close? Or do you see architecture-centric folders (Controllers/, Services/, Repositories/) at the top of src/?conventions/architecture/domain-driven-hexagonal.md__invoke / handle / execute), and the class name is <Verb><Noun>Controller.conventions/architecture/single-action-controllers.md, conventions/refactoring/anti-patterns/fat-controller.mdEntityManager, DataSource, DbContext, or ActiveRecord model usage outside of Repository classes.XxxRepositoryInterface, implementations are clearly named (DoctrineXxxRepository, TypeOrmXxxRepository), controllers do not touch persistence at all.$em->getRepository(...).conventions/architecture/repositories.mdThis is the single most important dimension for the Fire stage of the forge.
conventions/tdd/test-harness-requirements.md:
conventions/tdd/test-harness-requirements.mdCustomerId, Money, EmailAddress). HTTP boundary uses DTOs. Primitives appear only at the boundary.int, string, float everywhere.conventions/architecture/dtos-and-value-objects.md, conventions/refactoring/anti-patterns/primitive-obsession.md.aiforging/refactoring/patterns/ and .aiforging/refactoring/anti-patterns/ in the target./aiforging:setup installs the starter library.)conventions/refactoring/README.mdRough rubric (the analyzer should explain how it arrived at the score, not just emit a number):
| Score | Meaning |
|---|---|
| 9–10 | Already aligned. AI Forging will mostly add the refactor pattern library and reinforcing conventions. |
| 7–8 | Close. A few targeted refactors will bring it into alignment. |
| 5–6 | Mixed. The overall shape is workable but significant dimensions are poor. The proposed plan will be long. |
| 3–4 | Distant. Most dimensions are poor. Adoption is possible but expensive; recommend a phased approach. |
| 0–2 | Incompatible shape. Either the project was scaffolded from a very different template, or AI Forging is a poor fit for this codebase. Discuss with the human partner before proposing a plan. |
Do not claim false precision — if you can't tell whether a dimension is Mixed or Poor, say so. The point is honesty, not a number.
| Severity | Meaning |
|---|---|
| Critical | The Fire stage of the forge cannot run reliably until this is fixed. Blocks TDD for data-driven code. |
| High | Major deviation from architectural ideals. Refactor is worthwhile and likely to reveal latent bugs. |
| Medium | Deviation from conventions that's workable but should be fixed before the codebase grows further. |
| Low | Cosmetic or naming-only. Fix opportunistically during other refactors. |
| Info | Observation, not an action item. |
If no ProjectInfo was passed in, invoke the detector first and parse the JSON. Use the same uv-with-python3-fallback probe that /aiforging:setup uses, because uv is not guaranteed to be on PATH:
if command -v uv >/dev/null 2>&1; then FORGE_PY="uv run"; else FORGE_PY="python3"; fi
$FORGE_PY ${CLAUDE_PLUGIN_ROOT}/scripts/detect-project.py <target>
The detector script is a PEP 723 single-file script with no third-party deps, so python3 works identically to uv run.
Walk the target's src/ (or stack equivalent) — use Read, Glob, and Grep for everything. Do NOT shell out to write anything.
For each of the six dimensions above, gather evidence and decide the rating.
Compile findings. Assign severities.
Compute the score and write the summary.
Write the full report to <target>/.aiforging/ANALYSIS.md.
Return the top-line summary (score + top 3 findings by severity) to the caller.
<target>/.aiforging/ANALYSIS.md.${CLAUDE_PLUGIN_ROOT}/commands/setup.md — invokes this skill in Step 5.${CLAUDE_PLUGIN_ROOT}/conventions/architecture/${CLAUDE_PLUGIN_ROOT}/conventions/tdd/${CLAUDE_PLUGIN_ROOT}/conventions/refactoring/npx claudepluginhub aiforging/aiforging --plugin aiforgingProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.