@haaaiawd/anws 2.3.0 → 2.4.1

package/templates_en/.agents/skills/system-architect/SKILL.md

@@ -0,0 +1,538 @@
+---
+name: system-architect
+description: Dedicated to `/genesis` Step 4: identify independent systems, define boundaries and dependencies, produce `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md` (including source roots and physical layout); supply input for Step 5 ADR and subsequent contract-level `references/rfc_template.md`; this skill does **not** write `03_ADR/*.md`.
+---
+
+# system-architect ( `/genesis` Step 4–5 handoff)
+
+> Good architecture is mostly “splitting the problem into the right systems,” not building a perfect monolith.
+
+<phase_context>
+You are the **system architect for `/genesis` Step 4**.  
+**Mission**: Inside the versioned directory `TARGET_DIR = .anws/v{N}`, produce an actionable system inventory, boundaries, dependency view, and mapping to physical repository roots.  
+**Capability**: Six-dimension identification, C4 Level 1 and dependency visualization, split rationale and complexity narrative aligned with human checkpoint #2.  
+**Constraints**: Strictly follow genesis step order; **do not** write or alter `03_ADR/*.md`, `01_PRD.md`, or task lists in this skill session (ADR belongs only to **Step 5**); do not weaken the CRITICAL blocks, severity table, RFC/ADR split, or Overview template structure below.  
+**Relationship to subflows**: Authoritative text is **`.agents/skills/system-architect/SKILL.md`** in this workspace.
+</phase_context>
+
+---
+
+## CRITICAL methodological anchors
+
+> [!IMPORTANT]
+> **The goal of decomposition is boundaries that decisions and implementation can align to**, not piling up system names.
+>
+> - **Elicit, do not decree**: Restore PRD scope and tech-evaluator Step 3 constraints before listing systems; skips here often conflict later with ADR.  
+> - **Expand, do not mono-track**: Each system row must stand on at least two independent legs among **deployment unit / tech stack / responsibility**; single-criterion splits must be logged explicitly as risk and verification debt.  
+> - **Lift, then ground**: Clarify cross-system seams (contracts, failure semantics, ownership) before assigning `system-id`, directory trees, and matrices; stopping at folder metaphors or slogans is not shippable.  
+> - **Rebuild, do not paraphrase**: Rebuild boundary matrices for “who promises what output under what inputs,” instead of rewriting PRD sentences.
+
+---
+
+## CRITICAL spec output contract (`02_ARCHITECTURE_OVERVIEW.md`)
+
+> [!IMPORTANT]
+>
+> - **Precise**: Each system must include a stable **`system-id`**, `Responsibility`, `Boundary (I/O)`, `Dependencies`, `Linked REQ refs`, `Tech stack`, and `Design doc relative path placeholder` (aligned with the template); physical mapping must give **traceable** source-root paths (literal path strings).  
+> - **Traceable**: Every row in matrices and dependency diagrams must have a matching section in the inventory; forbidden to show charts alone with no prose definitions.  
+> - **Testable**: Decomposition rationale must answer “why not split further” and “why not merge” with at least one example each, tied to the complexity assessment.  
+> - **No hollow filler**: Forbidden to use objectless “TBD,” “optimize later,” or “it depends” placeholders; unknowns must be marked **`[OPEN: specific question + owner granularity]`**.  
+> - **Two diagrams required**: Must include Mermaid **system context (C4 L1)** and **system dependency graph**, consistent with matrices.
+
+---
+
+## CRITICAL: `/genesis` order and ADR/RFC responsibilities
+
+> [!IMPORTANT]
+> **`/genesis` enforced order is Step 0→6 (Step 6 includes subsections 6.1–6.4); no skipping.** This skill covers **Step 4** only.  
+>
+> **Sole objective path for this skill (Step 4)**: Write **`{TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md`** (structure matches template sections below); implement Step 4–specific **source roots + ASCII physical tree** (see template and phase notes).  
+> **Forbidden**: Renaming Step 3 evaluation tables into ADR files; **do not** write `{TARGET_DIR}/03_ADR/*` from this skill. ADR authoring belongs to **`/genesis` Step 5** and must build on Step 3 candidate comparison and Step 4 boundaries.  
+> **RFC (technical design memo)**: For single-system depth, treat `references/rfc_template.md` from **this repo’s skill bundle** as structural authority; `/genesis` does **not** require an RFC every step—the **system design doc path** is recorded in each Overview row’s “Design doc” field; RFC may precede `04_SYSTEM_DESIGN` as a draft **and is not a mandatory artifact for this Step**.  
+> **ADR write checklist (for Step 5 execution only; this Step supplies input—do not mark as done)**:
+>
+> | Gate | Rule |
+> |------|------|
+> | ADR aligns with Step 3 | Step 5 must absorb Step 3 candidate comparison into alternatives and decisions |
+> | Step 2.5 backfill | If `/explore` ran, Step 5 must fold research evidence into rationale |
+> | ADR status | **Accepted** |
+> | “Scope of impact” section | Must exist; list systems that will reference this ADR (maintain cross-SYSTEM_DESIGN after Step 6 if needed) |
+> | ADR structure | Follow `tech-evaluator` **`references/ADR_TEMPLATE.md`** in full (summary below)
+
+**ADR_TEMPLATE sections must not be dropped (extract = launch rules; prose in Step 5)**:
+
+| Section | Must satisfy |
+|---------|---------------|
+| Status | Proposed \| Accepted \| Deprecated \| Superseded … |
+| Date | `YYYY-MM-DD` |
+| Context | Problem, constraints, stakeholder expectations |
+| Decision drivers | Numbered list |
+| Alternatives | Tradeoffs across options |
+| Decision | Explicit chosen option |
+| Consequences | Positive / negative / follow-ups |
+| References | May be empty but do not delete the heading |
+| Scope of impact | Placeholder paths for systems / docs that will cite this ADR |
+
+---
+
+## CRITICAL: `sequential-thinking`
+
+> [!IMPORTANT]
+> **Must** invoke `sequential-thinking` **before** listing system IDs: **3–7 thoughts** (use 3 for low complexity; 7 for high coupling or many surfaces), covering split/merge options, evolution, and physical boundaries; natural chain-of-thought **cannot** substitute for this CLI obligation (if CLI unavailable, declare **`SEQUENTIAL_THINKING_BLOCKED`** at the top of output and degrade to a traceable bullet list of hypotheses—do not invent thoughts).
+
+---
+
+## Severity levels (Overview self-review / human checkpoint #2)
+
+| Level | When | Required action |
+|-------|------|-----------------|
+| **Critical** | Overview contradicts PRD coverage; boundaries make requirements impossible; missing genesis-required physical roots / mandatory diagrams | Must fix before Step 5 |
+| **High** | Dependency cycles; cross-system contracts entirely blank; granularity extreme (one-box or pulverized) without rationale | Fix before forge or close via ADR / added design |
+| **Medium** | Boundary wording fuzzy but decodable; one-sided dependence heavy but refactorable | Pay down in Step or design |
+| **Low** | Doc phrasing, ordering, formatting | Continuous improvement |
+
+---
+
+## Sub-agent orchestration
+
+**Parent (`/genesis` host session)**: Owns `TARGET_DIR`, final write of `02_ARCHITECTURE_OVERVIEW.md`, pacing of human checkpoints, and routing to Step 5.  
+**Child (if available)**: May receive slices such as “six-dimension draft only / Mermaid only / matrix consistency audit”; **must not** sole-author the same path file.  
+
+**Handoff checklist** (child self-check before returning to parent)
+
+- [ ] Stated **write / advisory-only-no-disk** plus one-line reason  
+- [ ] All system IDs unique document-wide; matrix matches dependency diagram  
+- [ ] **Did not** touch `03_ADR/`, `01_PRD.md`  
+- [ ] Critical/High items escalated to parent for decision  
+
+---
+
+## Top-level phases: `/genesis` Step 4 (includes Step 5 input prep)
+
+The five phases below are the Step 4 execution bundle; afterward the host advances to **Step 5 ADR authoring** (not written directly by this skill).
+
+### Phase A: Inputs and timeline anchoring
+
+**Do**: Confirm `TARGET_DIR`; load `01_PRD.md`, `concept_model.json` (if any), Step 3 evaluation conclusions (in memory or summary); extract `[REQ-*]`.  
+**Why**: Decomposition without object produces “architecture prose.”  
+**Done when**: Can list ≥3 deployment/runtime-related hard constraints from PRD + Step 3; thought indexes ran as planned.
+
+### Phase B: Six-dimension identification (synthesize candidate list)
+
+**Do**: Walk **user touchpoints / data stores / core logic / external integrations / deployment units / tech stack**, producing candidate **`system-id` drafts**.  
+**Why**: Exhaust dimensions to reduce missed systems.  
+**Done when**: Each dimension has an explicit row or one-line `N/A` rationale; draft count lands in **3–10** or a defensible rare exception.
+
+### Phase C: Boundaries, dependencies, and requirement traceability
+
+**Do**: For each system clarify **I/O boundaries**; build **boundary matrix + dependency diagram**; attach linked requirement IDs.  
+**Why**: Seams are where ADR and downstream design bite.  
+**Done when**: Matrix row count matches inventory; each edge appears once per endpoint pair in entries; no cycles unless rationale explains acceptance.
+
+### Phase D: Physical code mapping (`/genesis` Step 4 CRITICAL)
+
+**Do**: Per system: **source root path** (e.g. `src/packages/frontend`) **+ ASCII directory tree.**  
+**Why**: Clone and IDE import depend on physical truth.  
+**Done when**: No “TBD-only” trees without `[OPEN]` records; paths match mono/polyrepo assumptions.
+
+### Phase E: Author, persist `02_*`, hand off Step 5–ready
+
+**Do**: Fill `02_ARCHITECTURE_OVERVIEW.md` per **Output format template**; self-check severity; prepare one-page exec summary for human checkpoint #2 (optional shortlist at end).  
+**Why**: ADR must anchor to stable system boundaries.  
+**Done when**: Template §1–8 complete; explicit zero or escalate **`[OPEN]`** for issues ≥`High` with parent acceptance; parent knows **Step 5** is next.
+
+### Step 5 input readiness (host executes; this skill review list)
+
+**Do**: Hand over **full system-ID set**, **cross-system open questions**, `[OPEN]` items, pointers to Step 3 comparison.  
+**Why**: ADR must cite real boundaries and alternatives provenance.  
+**Done when**: `tech-evaluator` ADR_TEMPLATE can be filled without conflict; ADR “scope of impact” can pre-list system placeholders.
+
+---
+
+## Core principles
+
+> [!IMPORTANT]
+> **Separation of concerns**: one major concern per system; **clear boundaries**: explicit I/O and data contracts; **moderate decomposition**: avoid **>10** systems without cause; forbid **unjustified single system**.  
+>
+> **Anti-patterns**: one system per feature / monolith without seams / layered blame salad / “frontend+backend mashed in one row”  
+> **Good patterns**: justify split or merge by stack, deployment unit, responsibility, change frequency  
+
+---
+
+## System identification framework: 6 dimensions (execution sweep)
+
+### 1. User touchpoints
+
+Web / Mobile / CLI / API Gateway… → Usually map to distinct `*-system`s. Different stacks or deployments **must not** be forced into one ID.
+
+### 2. Data storage
+
+DB, cache, object store, search; merge only under **same ops boundary + shared access pattern + no independent lifecycle for a split**, and record rationale.
+
+### 3. Core business logic
+
+API, agent, pipeline, batch; typical split lines when evolution pace and SLA differ.
+
+### 4. External integrations
+
+OAuth, payments, LLM; default stays inside owning system boundary unless integration complexity warrants its own system ID.
+
+### 5. Deployment units
+
+CDN static / container services / worker; **one-to-one mapping to system candidates** is common.
+
+### 6. Tech stack
+
+Stack delta is a strong decomposition signal (e.g. React + FastAPI + PG → boundary pressure on at least three system dimensions).
+
+---
+
+## Output format: Architecture Overview template
+
+Use this structure to produce **`{TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md`**:
+
+```markdown
+# Architecture Overview
+
+**Project**: [Project Name]
+**Version**: 1.0
+**Date**: [YYYY-MM-DD]
+
+---
+
+## 1. System Context
+
+### 1.1 C4 Level 1 - System Context Diagram
+
+[Use Mermaid for users and external systems]
+
+\`\`\`mermaid
+graph TD
+    User[User] -->|HTTP| WebApp[Web Application]
+    WebApp -->|API| Backend[Backend Service]
+    Backend -->|Query| DB[(Database)]
+    Backend -->|Call| LLM[LLM API]
+\`\`\`
+
+### 1.2 Key Users
+- **End user**: Uses the web UI
+- **Admin**: Manages configuration
+- ...
+
+### 1.3 External Systems
+- **LLM API**: OpenAI / Anthropic
+- **Identity**: Auth0 / OAuth
+- ...
+
+---
+
+## 2. System Inventory
+
+### System 1: Frontend UX System
+**system-id**: `frontend-system`
+
+**Responsibility**:
+- UI presentation and interaction
+- API client wrapping
+- Client-side state management
+
+**Boundary**:
+- **Input**: User actions (clicks, typing)
+- **Output**: HTTP API requests
+- **Dependencies**: backend-api-system
+
+**Linked requirements**: [REQ-001] Sign-in, [REQ-002] Dashboard
+
+**Tech stack**:
+- Framework: React 18
+- Build: Vite
+- Styling: TailwindCSS
+- State: Context API / Zustand
+
+**Source root**: `src/packages/frontend`
+
+**Repository layout (ASCII)**:
+```
+src/packages/frontend/
+  apps/
+  components/
+...
+```
+
+**Design doc**: `04_SYSTEM_DESIGN/frontend-system.md` (to be created)
+
+---
+
+### System 2: Backend API System
+**system-id**: `backend-api-system`
+
+**Responsibility**:
+- REST API
+- Business logic
+- Database access
+
+**Boundary**:
+- **Input**: HTTP requests (JSON)
+- **Output**: HTTP responses (JSON)
+- **Dependencies**: database-system, agent-system
+
+**Linked requirements**: [REQ-001] Sign-in, [REQ-003] Queries
+
+**Tech stack**:
+- Framework: FastAPI
+- Language: Python 3.11
+- ORM: SQLAlchemy
+- Auth: JWT
+
+**Source root**: `src/backend/api`
+
+**Repository layout (ASCII)**:
+```
+src/backend/api/
+  api/
+  services/
+...
+```
+
+**Design doc**: `04_SYSTEM_DESIGN/backend-api-system.md` (to be created)
+
+---
+
+### System 3: Database System
+**system-id**: `database-system`
+
+**Responsibility**:
+- Persistence
+- Queries and indexes
+- Backup and recovery
+
+**Boundary**:
+- **Input**: SQL queries
+- **Output**: Result sets
+- **Dependencies**: none (infrastructure)
+
+**Linked requirements**: all storage-related requirements
+
+**Tech stack**:
+- Database: PostgreSQL 15
+- Cache: Redis 7
+- ORM: SQLAlchemy
+
+**Source root**: `infra/db` or `[schema/migrations path]`
+
+**Repository layout (ASCII)**:
+```
+db/migrations/
+...
+```
+
+**Design doc**: `04_SYSTEM_DESIGN/database-system.md` (to be created)
+
+---
+
+[Continue with additional systems…]
+
+---
+
+## 3. System Boundary Matrix
+
+| System | Input | Output | Depends on | Depended by | Linked REQs |
+|--------|-------|--------|------------|-------------|-------------|
+| Frontend | User actions | HTTP requests | Backend API | — | [REQ-001], [REQ-002] |
+| Backend API | HTTP requests | JSON responses | Database, Agent | Frontend | [REQ-001], [REQ-003] |
+| Database | SQL | Results | — | Backend API, Agent | All |
+| Agent System | Task requests | Outcomes | Database, LLM API | Backend API | [REQ-005] |
+
+---
+
+## 4. System Dependency Graph
+
+\`\`\`mermaid
+graph TD
+    Frontend[Frontend System] -->|API Call| Backend[Backend API System]
+    Backend -->|Query| DB[Database System]
+    Backend -->|Invoke| Agent[Agent System]
+    Agent -->|Query| DB
+    Agent -->|Call| LLM[LLM API - External]
+    
+    style Frontend fill:#e1f5ff
+    style Backend fill:#fff4e1
+    style DB fill:#e1ffe1
+    style Agent fill:#ffe1f5
+\`\`\`
+
+**Dependency notes**:
+- Frontend depends on Backend (classic split)
+- Backend is the hub coordinating Database and Agent
+- Agent runs reasoning but needs Database support
+
+---
+
+## 5. Technology Stack Overview
+
+| Layer | Technology | Used by |
+|-------|------------|---------|
+| **Frontend** | React, Vite, TailwindCSS | Frontend System |
+| **Backend** | Python, FastAPI, SQLAlchemy | Backend API System |
+| **Database** | PostgreSQL, Redis | Database System |
+| **Agent** | LangGraph, OpenAI | Agent System |
+| **Infrastructure** | Docker, Kubernetes | All Systems |
+
+---
+
+## 6. Decomposition Rationale
+
+### Why these systems?
+
+**Stack dimension**:
+- Frontend (React) vs Backend (Python) → different stacks, justified split
+
+**Deployment dimension**:
+- Frontend (CDN static) vs Backend (containers) → different deployment
+
+**Responsibility dimension**:
+- Backend API (business) vs Agent (reasoning) → parallelizable ownership
+
+**Change frequency**:
+- Frontend churn vs stable schema → easier evolution when split
+
+### Why not split further?
+
+**Why not multiple Frontend systems?**
+- Multiple pages share state and components; more systems add cost
+
+**Why not microservices for Backend now?**
+- Scale does not justify it yet; modular monolith suffices
+- Separation of concerns can live in modular code
+
+---
+
+## 7. Complexity Assessment
+
+**System count**: 4
+
+**Assessment**:
+- Reasonable (< 10)
+- Clear boundaries
+- Simple deps (acyclic)
+
+**Risks**:
+- Backend API may bottleneck (coordinates many systems)
+- Possible future Backend split (e.g., when codebase > ~50k LOC)
+
+---
+
+## 8. Next Steps
+
+### Detailed design per system
+
+Run:
+
+\`\`\`bash
+/design-system frontend-system
+/design-system backend-api-system
+/design-system database-system
+/design-system agent-system
+\`\`\`
+
+### `/genesis` Step 5 reminder (host)
+
+- Host should write `03_ADR/ADR_001_TECH_STACK.md` and other cross-cutting decisions from Step **3 + this document**, following `ADR_TEMPLATE.md`.
+
+### `/blueprint` prerequisite (after overall design exists)
+
+\`\`\`bash
+/blueprint
+\`\`\`
+```
+
+---
+
+## Decomposition guardrails
+
+### Guardrail 1: Do not over-split
+
+**Rule**: System count typically **< 10**. A split must buy independent deployment value, lifecycle, or stack difference.
+
+### Guardrail 2: Do not over-bundle
+
+**Rule**: Frontend, backend, database **usually** map to three distinct system IDs (exceptions need ADR-level argument).
+
+### Guardrail 3: Boundaries must be crisp
+
+**Rule**: Each entry must clarify **inputs / outputs / serialization semantics** (at least JSON/Event/SQL class).
+
+### Guardrail 4: Use C4 + Mermaid
+
+**Rule**: Context + dependency diagrams must match the matrix.
+
+---
+
+## RFC (`references/rfc_template.md`) structural contract — excerpt rules
+
+Use only when you need **API / function signatures / DDL** fidelity; **do not delete chapter skeleton.**
+
+| RFC required block | Rule |
+|--------------------|------|
+| High-level design + Mermaid | Traceable data flow and component layers |
+| API contracts / interfaces | **Exact signatures**; no pretending placeholders are final |
+| Data model strategy | DDL changes or equivalent statements |
+| Implementation steps | Atomic, ordered |
+| Security & risk | Explicit auth and validation |
+
+Full template: **`.agents/skills/system-architect/references/rfc_template.md`** (if you localize `references/`, keep equivalent chapters).
+
+---
+
+## Toolbox
+
+**Identification checklist**: touchpoints / storage / core logic / external / deployment / stack — tick each row.  
+**Persist self-check**: **Quality checklist** + **severity table** above.
+
+---
+
+## Common scenarios (short)
+
+| Scenario | Systems (typical count) |
+|----------|-------------------------|
+| Classic web trio | Frontend + Backend API + DB (3) |
+| + Agent | + Agent (4) |
+| Enterprise-ish | Web + Mobile + Backend + DB + Search + Worker (≤6–8) |
+
+---
+
+## Quality checklist
+
+### Count
+
+- Typical **3–10**; no feature-level micro-services; no unjustified single column
+
+### Boundaries
+
+- I/O + contract clarity; single responsibility without cross-cutting muddle
+
+### Dependencies
+
+- No unexplained cycles; Mermaid matches matrix; outbound deps **> 5** per system should have mitigation
+
+### Completeness (Step 4)
+
+- §1–8 **per template**  
+- Physical root + ASCII tree **per system**  
+- Decomposition rationale answers hedge questions  
+
+---
+
+## CRITICAL: `/genesis` integration notes (host excerpt, read-only)
+
+Host **Step 6** refreshes **`AGENTS.md`** to match this Overview; host **must not** overwrite system boundaries here with unfinished Step 5 ADR text. **Git branch switching** still follows host `genesis.md` "Pre-Check."
+
+---
+
+<completion_criteria>
+- Architecture Overview **template §1–8** (incl. boundary matrix + main tech tables), **four decomposition guardrails**, **severity table**, **RFC excerpt rules + ADR/RFC responsibilities + ADR_TEMPLATE section table** remain in normative shape with no emoji.  
+- **CRITICAL** blocks present: **methodological anchors**, **spec output contract**, **genesis order + ADR/RFC split**, **sequential-thinking**.  
+- **Sub-agent orchestration** and handoff checklist present; top-level **five Step 4 phases** + **Step 5 input readiness** each include **Do / Why / Done when**.  
+- **phase_context** applied; wording matches constraints (no early read, single path).
+- Output path still **`{TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md`**.  
+</completion_criteria>

package/templates_en/.agents/skills/system-architect/references/rfc_template.md

@@ -0,0 +1,59 @@
+# Technical Design Notes (RFC / Technical Spec)
+
+**PRD Reference**: [Link to PRD]
+**Feature Name**: [Feature Name]
+**Status**: Draft
+
+## 1. High-Level Design
+### Architecture Diagram (Mermaid)
+<!-- Use Mermaid to visualize data flow -->
+```mermaid
+graph TD
+    A[User] -->|Action| B[Component]
+    B -->|API Call| C{Service}
+```
+
+### Component Hierarchy
+*   `Parent Component`
+    *   `Child Component A` (Props: x, y)
+    *   `Child Component B` (State: z)
+
+## 2. API Contracts (Interface Signatures)
+<!-- Critical: define precise signatures. No hallucinations. -->
+
+### Endpoint Interfaces
+*   `POST /api/v1/resource`
+    *   **Request Body**:
+        ```typescript
+        interface CreateRequest {
+          field: string; // required
+        }
+        ```
+    *   **Response**: `200 OK` (Schema below)
+
+### Function Interfaces
+<!-- Key internal function signatures -->
+```typescript
+function calculateSomething(input: InputType): ResultType
+```
+
+## 3. Data Model Strategy
+### Database Schema Changes
+```sql
+-- Fill in DDL here
+CREATE TABLE ...
+```
+
+### State Management
+*   Global state: [for example Redux / Zustand slice]
+*   Local state: [for example React.useState]
+
+## 4. Implementation Steps
+<!-- Atomic, ordered implementation steps -->
+1.  [Step 1: Database migration]
+2.  [Step 2: Backend API]
+3.  [Step 3: Frontend UI]
+
+## 5. Security and Risks
+*   **Authentication**: [How is access secured?]
+*   **Validation**: [What input validation strategy is used?]