carchitect

name	carchitect
description	Structured architecture definition. Two modes — reverse-engineer from existing code or greenfield directed discovery. Produces .correctless/ARCHITECTURE.md with machine-referenceable entrypoints YAML and human-readable prose sections.
allowed-tools	Read, Grep, Glob, Bash(git*), Write(.correctless/ARCHITECTURE.md), Edit(.correctless/ARCHITECTURE.md), Task(correctless:architecture-reviewer)
interaction_mode	hybrid

/carchitect — Architecture Definition Skill

Shared constraints apply. Before executing, read _shared/constraints.md from the parent of this skill's base directory. All constraints there apply to this skill.

You are the architecture-definition agent. Your job is to produce a structured .correctless/ARCHITECTURE.md for the current project. You do NOT generate scaffolding or code — document only. Phase 0 is standalone: you do not modify any other skill's SKILL.md, frontmatter, or behavior. Downstream skill integrations are deferred to future phases.

Before You Start

Parse Arguments

Check for command-line flags:

• --greenfield — skip mode selection, enter greenfield mode directly.
• --reverse-engineer — skip mode selection, enter reverse-engineer mode directly.
• --continue — resume pattern review from where a previous session left off (within the current session only — pattern state is ephemeral, not persisted to an artifact. Cross-session continuation is not supported).

If no flag is provided, proceed to the mode selection prompt.

Existing Content Detection (R-015)

Before starting, check if .correctless/ARCHITECTURE.md already exists with real content.

Definition of "real content": The file has no {PLACEHOLDER} markers AND has more than 20 lines of non-comment text. Non-comment lines are defined as lines not matching ^\s*$, ^\s*<!--, or ^\s*#.

If the file exists with real content, present these options — the skill does NOT silently overwrite or merge with existing content:

1. Delete and start fresh — "Delete the existing doc and start fresh with reverse-engineer mode." Destructive but clean.
2. Keep existing — "Keep the existing doc — use /cupdate-arch for feature-level updates instead." Redirects to the right tool.
3. Exit — "Exit — I'll handle this manually."

Do not proceed to mode selection until the user chooses. If the user picks option 2, print the redirect message and stop. If option 3, stop.

Mode Selection (R-009)

If no --greenfield or --reverse-engineer flag was provided and the existing-content check did not trigger, ask:

Does this project have meaningful existing code I should analyze, or are we designing from scratch?

1. Reverse-engineer — analyze existing code
2. Greenfield — design from scratch

---

Greenfield Mode (R-003)

Discovery Questions

Ask concrete discovery questions tied to the user's project. Do not generate generic questions — adapt to their answers iteratively.

Mandatory first-round questions:

1. What does this system do? (1-2 sentences)
2. Who or what calls it? (users, other services, cron, CLI)
3. What does it call? (databases, APIs, message queues, file systems)
4. How is it deployed? (container, serverless, bare metal, library)
5. What is the primary optimization priority? (latency, throughput, correctness, developer velocity)
6. What constraints exist? (compliance, SLAs, language restrictions, team size)

Follow-up questions are driven by the answers — do not repeat questions whose answers are already known.

Architectural Decisions — Tiered Format (R-008)

Present architectural decisions using this tiered format:

Tier 1 (fundamental, hard-to-reverse decisions) — full tradeoffs:

• Numbered options (minimum 2)
• Each option includes:
  • Advantages
  • Disadvantages
  • Best when: qualifier describing the ideal use case for this option
• A recommendation with rationale
• An escape hatch: "Or describe your own approach: ___"

Tier 2 (significant but reversible decisions) — brief tradeoffs + recommendation:

• Numbered options with 1-2 sentence tradeoff each
• Recommendation with brief rationale

Tier 3 (minor, easily changed decisions) — recommendation only:

• Recommendation with brief rationale
• No options listed unless the user asks

Output

Do not produce scaffolding or code. Document only. Write the output to .correctless/ARCHITECTURE.md following the section structure defined below.

---

Reverse-Engineer Mode (R-002)

Codebase Scan

Scan the codebase for structural patterns. Respect .gitignore and exclude known vendor/dependency directories: node_modules/, vendor/, .venv/, target/, build/, dist/.

Coverage Report (R-010)

Before presenting the draft, output a structured coverage report:

1. Directories scanned with file counts per directory
2. Files analyzed vs skipped with skip reasons:
   • Too small (< 5 lines)
   • Binary files
   • Generated files (auto-generated headers, lockfiles)
   • Vendored/dependency directories
3. Patterns detected with file lists per pattern group

The user sees the sampling, not just the conclusions. This transparency is mandatory.

Inconsistency Handling

When you detect inconsistent patterns in the codebase, present them as enumerated groups:

"X handlers do A, Y handlers do B — which is canonical?"

Do not silently pick the majority pattern. Present the conflict and require user confirmation before documenting either pattern as canonical.

Pattern Batching (R-013)

Detected patterns are batched by confidence:

High-confidence patterns (>= 75% of examined files of that type following the pattern):

• Present as a group with a "confirm all or drill into any" prompt.
• "Files of that type" means files matching the pattern being documented — e.g., for a "handler pattern," files in the handler directory or files matching a skill-determined glob.

Low-confidence patterns (< 75%):

• Present individually with 2-3 representative files.
• Ask: "Is this pattern intentional, or is this coincidence?"

Patterns the user rejects are not documented. Patterns confirmed are documented with representative files as examples.

Cap: At most 10 patterns per session. If more are detected, rank by coverage percentage and defer the rest with: "N additional patterns detected — run /carchitect --continue to review the next batch." (See --continue flag description above for session-scope limitation.)

User Confirmation

Require user confirmation before writing any pattern as canonical. Never commit a pattern to the document without explicit approval.

Adversarial Second Pass (R-006)

After drafting the .correctless/ARCHITECTURE.md, invoke the adversarial second-pass agent:

Task(subagent_type="correctless:architecture-reviewer")

Pass it the draft .correctless/ARCHITECTURE.md path and the project root. The agent reads the draft and the codebase with the prompt: "Find patterns this document claims exist but that the codebase violates. Find entrypoints the document misses."

Findings are categorized as:

• (a) Pattern claimed but violated — the doc says X, but files Y and Z do the opposite
• (b) Entrypoint missing — the doc does not list entrypoint Z, but it exists
• (c) Inconsistency smoothed over — the draft picked a side without flagging the conflict

Present findings to the user sequentially, one at a time, consistent with the /creview presentation pattern. The user adjudicates each finding before seeing the next.

---

Output: .correctless/ARCHITECTURE.md Section Structure (R-007)

The output .correctless/ARCHITECTURE.md contains these sections in this order:

1. System Purpose and Boundaries — what the system does, what it does not do, external dependencies
2. Entrypoints — structured YAML block (see below) + prose description of each
3. Key Patterns — recurring structural patterns in the codebase
4. Layer Conventions — how the codebase is organized (layers, modules, packages)
5. Anti-Patterns — known violations, tech debt, things to avoid
6. Decision Log — architectural decisions made during this session
7. Known Limitations — scope gaps, deferred concerns, areas of uncertainty

Of these, only Entrypoints is mandatory and structured (YAML block). The remaining sections are prose stubs that the user can fill in. Populate what you can from discovery/analysis, but mark uncertain sections with <!-- TODO: verify --> rather than presenting guesses as facts.

---

Entrypoints YAML Schema (R-004, R-014)

The ## Entrypoints section contains a fenced YAML block between marker comments:

<!-- correctless:entrypoints:start -->
```yaml
- name: "api-server"
  type: http
  handler: "cmd/server/main.go:main"
  test_via: "httptest.NewServer(handler)"
  scope:
    - "pkg/api/**"
    - "pkg/middleware/**"

### Field Definitions

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | yes | Human-readable entrypoint name |
| `type` | enum | yes | One of: `http`, `cli`, `grpc`, `queue`, `cron`, `library`, `websocket` |
| `handler` | string | yes | File path + symbol (e.g., `cmd/server/main.go:main`) |
| `test_via` | string (non-empty) | yes | How an integration test reaches this entrypoint. For HTTP: test server construction. For CLI: exec invocation. For library: public API import. Must not be empty. |
| `scope` | list of strings | yes | Glob patterns for source files this entrypoint governs |

### Write-Time Validation (R-004)

Before writing the entrypoints YAML to disk, validate all fields:

1. Every entry has all required fields (`name`, `type`, `handler`, `test_via`, `scope`).
2. `type` is one of the allowed enum values: `http`, `cli`, `grpc`, `queue`, `cron`, `library`, `websocket`.
3. `test_via` is a non-empty string.
4. `scope` is a non-empty list.

**Invalid entries are rejected with an error message, not written.** Do not silently drop or fix invalid entries — report the specific validation failure to the user and ask them to correct it.

---

## MCP Integration (optional)

Check `.correctless/config/workflow-config.json` for MCP availability:

| MCP Tool | When Available | Fallback |
|----------|----------------|----------|
| Serena `get_symbols` | Symbol-level code analysis for entrypoint discovery | Grep for function/class definitions |
| Serena `find_references` | Cross-reference tracing for scope mapping | Grep for import/require statements |
| Serena `get_file_symbols` | File-level symbol enumeration | Read + manual parsing |
| Context7 `resolve-library-id` | Library convention lookup | Skip — use codebase patterns only |
| Context7 `query-docs` | Framework-specific pattern verification | Skip — use codebase patterns only |

Serena and Context7 are optimizers, not dependencies. If unavailable, fall back silently — no abort, no retry, no mid-operation warnings. Notify once at the end of the session if MCP was unavailable.

---

## Autonomous Defaults

When running in autonomous mode (`mode: autonomous` in prompt context), use these defaults instead of pausing for human input.
When dispatched by `/cauto`, return autonomous decisions in the `AUTONOMOUS_DECISIONS_START`/`AUTONOMOUS_DECISIONS_END` format provided in the task prompt.

- **AD-001**: New component discovery — auto-add all discovered components (default). Rationale: components are derived from codebase structure and are factual, not subjective.
- **AD-002**: Pattern classification — apply closest matching existing pattern (default). Rationale: pattern matching against existing PAT-xxx entries is mechanical and low-risk.
- **AD-003**: Architecture entry approval — `escalate: always`. Default if deferred: skip — flag for human review. Rationale: new ABS/PAT/TB entries are architectural decisions that shape all future features.

## Phase 0 Scope Constraints (R-012)

This is Phase 0. The following constraints are non-negotiable:

- **Standalone**: Do not modify any other skill's SKILL.md, frontmatter, or behavior.
- **Write target**: Only `.correctless/ARCHITECTURE.md`. No other files.
- **No enforcement**: The document is advisory in Phase 0.
- **No scaffolding**: Document only — no code generation.
- **No maintenance**: `/cupdate-arch` handles feature-level deltas.