From hitl
Architect review of an existing codebase. Reads the system manifest and code to reconstruct what architectural decisions were already made, interviews the architect to confirm rationale and constraints, then documents them as real ADRs. Run during brownfield onboarding after the system manifest is generated and before incremental feature work begins.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hitl:architect-review-existing [optional: focus area or specific concern][optional: focus area or specific concern]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Before doing anything else:** Check whether `.hitl/` exists in the current directory. If it does not, stop immediately and output this — do not proceed with any steps:
Before doing anything else: Check whether .hitl/ exists in the current directory. If it does not, stop immediately and output this — do not proceed with any steps:
This project hasn't been set up for HITL.
To get started, run one of these commands in your project directory:
/hitl:dev-start-from-prd new project from a PRD
/hitl:dev-start-brownfield adopt HITL on an existing codebase
/hitl:dev-start-migration migrate a system
Reconstructing the architectural decisions already baked into this codebase, documenting them as ADRs, and surfacing concerns before incremental feature work begins.
Graphify pre-flight:
[ -f graphify-out/graph.json ] && echo "Graphify: available" || echo "Graphify: unavailable"
State the result once and apply it throughout.
1a. Load the system manifest:
Read docs/system-manifest.yaml. Summarize:
If no manifest exists, say: "System manifest not found. Run Step 3 of /hitl:dev-start-brownfield first to generate it, then re-run this skill."
1b. Survey key technology indicators:
Read the following files (whichever exist) to identify the technology stack:
| What to look for | Where to look |
|---|---|
| Language / runtime | package.json, pom.xml, build.gradle, requirements.txt, pyproject.toml, go.mod, Gemfile, *.csproj |
| Web framework | Framework-specific config files, main entry point, routing files |
| Database | Migration files (db/migrate/, alembic/, flyway/, liquibase/), ORM config, connection strings in env examples |
| Auth approach | Auth middleware, auth/, security/, JWT/session config |
| API style | Route definitions — REST endpoints vs GraphQL schema vs gRPC .proto files |
| Deployment target | Dockerfile, docker-compose.yml, k8s/, terraform/, serverless.yml, *.yaml in .github/workflows/ |
| Test framework | jest.config.*, pytest.ini, spec/, __tests__/, test runner in CI config |
| Key patterns | Event bus config, message queue, CQRS/event-sourcing markers, cache layer |
Use Graphify if available:
/graphify query "technology stack framework database auth deployment"
After reading, output a Tech Stack Summary:
Language/runtime: [e.g., Java 21 / Spring Boot 3.2]
Database: [e.g., PostgreSQL 15, Flyway migrations]
Auth: [e.g., JWT, RS256, issued by internal auth service]
API style: [e.g., REST, OpenAPI 3.1 spec in docs/api/]
Deployment: [e.g., Docker → Kubernetes (GKE), Helm charts in k8s/]
Test framework: [e.g., JUnit 5 + Mockito, Testcontainers for integration]
Notable patterns: [e.g., Hexagonal architecture, domain events via Spring Events]
For each category below, read the relevant code and identify the concrete decision that was made. Do not infer intent — only record what exists.
Decision categories:
Service architecture — monolith, microservices, modular monolith? How are modules/services separated? Are domain boundaries clean or tangled?
Data architecture — relational vs document vs hybrid? ORM vs raw SQL? Single DB vs per-service? Shared DB across domains (a risk)?
Auth and identity — where does auth live? Centralized service or per-component? Token type and signing approach? Who issues tokens?
API contract — REST vs GraphQL vs gRPC vs event-driven? Is there a published contract (OpenAPI spec, Proto files)? Versioning approach?
Cross-domain communication — direct calls vs message queue vs event bus? Synchronous vs async? Are there circular dependencies?
Deployment and infrastructure — containerized? Orchestrated? Cloud provider? IaC tool? Is infra in this repo or a separate one?
Test strategy as-built — what test layers actually exist (unit/integration/E2E)? What coverage exists? What is conspicuously absent?
Non-obvious patterns — any patterns that deviate from the obvious approach for this stack (event sourcing, CQRS, strangler fig, saga, etc.)?
Observability as-built — what structured logging library is in use and what format (JSON, plain text)? Are metrics emitted (Prometheus, Datadog, CloudWatch)? Is there distributed tracing (OpenTelemetry, Datadog APM, Jaeger)? Error tracking (Sentry, Rollbar)? Are dashboards and alert rules defined in the repo? Is there a documented on-call routing structure?
Present findings as a numbered decision list:
Decision 1 — Service architecture: [what exists]
Decision 2 — Data architecture: [what exists]
...
Then ask: "Does this match your understanding of the codebase? Any decisions I missed or got wrong?"
For each decision identified in Phase 2, ask the following (group them — do not ask one at a time for every decision):
Round 1 — Intent:
"For each of these decisions, was it: (a) a deliberate architectural choice, (b) inherited from a previous team or framework default, or (c) evolved over time without a formal decision? [list decisions]"
Round 2 — Rationale (for deliberate choices only):
"For the deliberate decisions — what problem was each solving at the time? What alternatives were considered?"
Round 3 — Constraints and regrets:
"Which of these decisions creates the most constraints on future changes? Are there any you would make differently today? Any that are actively causing pain?"
Round 4 — Unknown decisions:
"Are there any significant architectural decisions I didn't surface that should be documented — things that would surprise a new team member or that every developer needs to know?"
Record answers alongside each decision.
Before creating any new ADRs, ensure the baseline stubs are present and offer the architect the chance to fill in any of them now.
Step 1 — Copy any missing stubs:
ls docs/02-design/technical/adrs/adr-000*.md 2>/dev/null
If any of the 8 baseline stubs are missing, copy them now from the plugin:
PLUGIN_ROOT=$(python3 -c "
import json,os,sys
try:
d=json.load(open(os.path.expanduser('~/.claude/plugins/installed_plugins.json')))
for inst in d.get('plugins',{}).get('hitl@hitl',[]):
p=inst.get('installPath','')
if os.path.isfile(os.path.join(p,'.claude-plugin/plugin.json')):
print(p);sys.exit(0)
except:pass
try:
d=json.load(open(os.path.expanduser('~/.claude/settings.json')))
for p in d.get('plugins',[]):
path=p if isinstance(p,str) else p.get('path','')
if os.path.isfile(os.path.join(path,'.claude-plugin/plugin.json')):
print(path);sys.exit(0)
except:pass
" 2>/dev/null)
mkdir -p docs/02-design/technical/adrs
for f in "$PLUGIN_ROOT/shared/templates"/adr-000*.md; do
dest="docs/02-design/technical/adrs/$(basename "$f")"
[[ -f "$dest" ]] || cp "$f" "$dest"
done
Step 2 — Present the full baseline menu and let the architect choose:
Output this table:
| ADR | Topic | What it covers | Gates |
|---|---|---|---|
| 0001 | HITL adoption | Why HITL was adopted, expected ROI | — (pre-filled) |
| 0002 | Documentation-first | Docs-before-code policy | — (pre-filled) |
| 0003 | Test strategy | Framework, coverage threshold, mocking policy, CI gate | First Tier 2 change |
| 0004 | Change tier policy | Tier classification thresholds for this project | First Tier 2 change |
| 0005 | Observability strategy | Logging, metrics, tracing, error tracking, alerting, on-call, token cost | First Tier 2 prod deploy |
| 0006 | Branching and PR strategy | Branching model, naming, PR size, reviewers by tier, merge strategy | First PR |
| 0007 | Security baseline | Secret management, dependency scanning, SAST, security review gates, compliance | First Tier 2 prod deploy |
| 0008 | Data backup and recovery | RTO/RPO, backup approach per store, restore procedure, verification cadence | First prod data write |
Then ask:
"These are the 8 baseline ADRs for this project. ADR-0001 and ADR-0002 are pre-filled — I'll confirm the dates are correct.
For the remaining 6, which would you like to complete now? You can fill in all of them, pick a few to start, or defer them all. I'll pre-fill every field I can from the code and architecture review — you only need to answer what I can't infer."
Step 3 — Fill in whichever the architect selects:
For each ADR the architect wants to complete:
Step 4 — Note what remains outstanding:
After filling in the selected ADRs, list any deferred stubs and what they gate:
"Still outstanding: [list]. These can be filled in at any time by re-running
/hitl:architect-review-existing. Note that [ADR-XXXX] is needed before [gate] — flag this with the team."
For each decision that was deliberate, has significant constraints, or would surprise a new team member — create a real ADR in docs/02-design/technical/adrs/.
Use the next available number after the baseline stubs (start from ADR-0009 unless higher-numbered ADRs already exist).
ADR format (follow the same structure as adr-0001-hitl-adoption.md — confirmed present from 4a above — use it as the reference for section headings and the ROI Estimate block):
| Field | What to fill in for brownfield ADRs |
|---|---|
| Status | Accepted if already in production; Under review if the team questions it |
| Date | Best estimate of when the decision was made — ask if unknown |
| Context | What was the situation that led to this choice? |
| Decision | What exactly was decided — specific, not vague |
| Alternatives considered | What was evaluated at the time (ask architect; OK to say "not documented" if unknown) |
| Consequences | What does this decision constrain or enable? |
| Open questions | Any active debate about whether this should change? |
Prioritize ADRs for:
Skip ADRs for:
After creating each ADR, confirm with the architect: "Does this accurately capture the decision and its rationale?"
Using the infrastructure files already read in Phase 1b (Dockerfile, docker-compose.yml, k8s/, terraform/, serverless.yml, CI/CD configs) and the deployment decision confirmed in Phase 3, generate docs/02-design/technical/hld/deployment-view.md.
If no infrastructure files were found in Phase 1b (no Dockerfile, no k8s/, no terraform/, no CI/CD config): skip this step and flag it in Phase 5 as a 🟡 concern: "Deployment not captured in IaC or config — deployment view cannot be generated."
Otherwise, create the file with this structure (fill in from the actual manifests — do not leave template placeholders):
# Deployment View
> Generated from IaC and deployment config during brownfield onboarding.
> Update this document when infrastructure changes.
## Summary
[One paragraph: cloud provider, orchestration layer, key deployment technology — e.g. "Deployed as Docker containers orchestrated by Kubernetes on GKE. Infrastructure managed with Terraform. CI/CD via GitHub Actions."]
## Environments
| Environment | URL / endpoint | Notable differences from production |
|---|---|---|
| Production | [from IaC/config] | — |
| Staging | [from IaC/config] | [e.g., single replica, smaller DB tier] |
| Development | local / docker-compose | [e.g., no TLS, mock external services] |
Fill each row from what the IaC and CI/CD config actually say — leave a cell blank only when the information is genuinely absent from the files.
## Infrastructure Diagram
<!-- Node labels must be single-line. Quote labels containing (), -, or /. No <br/> tags. -->
\`\`\`mermaid
graph TB
subgraph prod["Production"]
ing["Ingress / Load Balancer"] --> api["API Service"]
api --> db[("Database")]
api --> cache[("Cache")]
end
ext["External Services"] --> api
\`\`\`
Replace the template nodes above with actual services and components from k8s/ or terraform/. Include: ingress/load balancer, application services, databases, caches, queues. Group by environment where relevant.
## Services and Containers
| Service | Image / runtime | Port | Replicas | Purpose |
|---|---|---|---|---|
| [from Dockerfile or k8s Deployment manifests] | | | | |
## External Dependencies
| Service | Type | Used for |
|---|---|---|
| [third-party APIs, managed cloud services, identity providers — from env examples and connection configs] | | |
## CI/CD Pipeline
<!-- Node labels must be single-line. No <br/> tags. -->
\`\`\`mermaid
flowchart LR
commit["Git commit"] --> ci["CI: test + build"]
ci --> staging["Deploy staging"]
staging --> gate{"Manual gate?"}
gate -- yes --> approval["Approval"]
gate -- no --> prod["Deploy production"]
approval --> prod
\`\`\`
Replace this template with the actual pipeline steps from the CI/CD config files.
## Gaps and Notes
- [Infrastructure not yet captured in IaC]
- [Environments referenced in code but absent from config]
- [Anything the architect clarified verbally in Phase 3 that does not appear in files]
After saving the file:
docs/02-design/technical/hld/index.md — add a row for the deployment view. If the index file does not exist, create it:
# HLD Index
| Document | Scope | Status | Date |
|---|---|---|---|
| [Deployment View](deployment-view.md) | System-wide | Baseline | [today's ISO date] |
grep -n '<br' docs/02-design/technical/hld/deployment-view.md — output must be empty.Review the complete picture — system manifest, tech stack, decisions, ADRs — and identify concerns that the team should address before or during incremental HITL work.
Categorize each concern:
🔴 Blocks or complicates HITL compliance:
/hitl:architect-design-feature cannot validate interface conformance🟡 Should be addressed within the first few changes:
/hitl:dev-generate-docs before first change to each🟢 Worth noting but not blocking:
Output the concern list and ask: "Any of these concerns a surprise? Any I missed?"
Output this exactly (fill in the blanks):
Architecture review complete.
Decisions documented: [List each ADR created with its title and file path]
Deployment view: [path to deployment-view.md if generated, or "skipped — no IaC files found"]
Key constraints for the team: [2–4 bullet points — the most important things every developer must know before starting a change]
Before your first Tier 2 change: [List any 🔴 concerns that need resolution — e.g., "Complete ADR-0003 (test strategy) — the coverage gate cannot be enforced until the test framework is chosen"]
Ready for: Step 7 of /hitl:dev-start-brownfield — identifying priority components for incremental documentation.
npx claudepluginhub pappar/hitl-claude-plugin --plugin hitlGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.