thachvd-kit 1.0.14 → 1.0.16

package/kit/PROMPT_RECIPE.md

@@ -1,52 +1,30 @@
-# 📜 PROMPT RECIPES - Coding Agent Strategy
-
-Use these templates to enforce modular design, clean architecture, and contextual awareness in any project.
-
----
-
-## 🏗️ 1. Project Initiation (Architecture First)
-Use this when starting a new project. Force the Agent to design the structure before writing any code.
-
-> "I want to initialize a new project: [Project Name]. 
-> **Stack:** [e.g., Next.js, FastAPI, Flutter, etc.]
-> 
-> **Architectural Requirements:**
-> 1. Follow a **Modular & Scalable** approach. Keep components atomic and logic decoupled.
-> 2. **State Management:** Use [e.g., Zustand, Redux, Provier, or none] with a modular pattern.
-> 3. **Separation of Concerns:** Keep business logic outside of UI files (use services/use-cases/lib).
-> 4. **Resource Management:** Offload heavy computations or system-level tasks to [e.g., Rust, Go, or Backend].
-> 5. **Constraints:** Enforce a maximum of **250 lines per file** to ensure atomicity.
-> 
-> Please propose a detailed **File Tree** and explain the responsibility of each directory before implementation."
-
----
-
-## ⚡ 2. Complex Feature Implementation
-Use this for hard tasks that require deep thinking.
-
-> "I need to implement the following feature: [Feature Description].
-> 
-> **Execution Workflow:**
-> 1. Analyze the project baseline from `PROJECT_CONTEXT.md`.
-> 2. Propose a **Data Flow Diagram** or a sequence of operations.
-> 3. Break down the task into small, manageable files: State/Store, Logic/Service, and UI/Component.
-> 4. Ensure compliance with the project's **Clean Code** standards."
-
----
-
-## 🐞 3. Systemic Debugging
-Use this when facing logic errors or unexpected behavior.
-
-> "The application is encountering the following issue: [Error Description].
-> 
-> **Instructions:**
-> 1. Identify the **Root Cause** by inspecting logs or using diagnostic tools.
-> 2. Verify if this issue impacts the system assumptions defined in `PROJECT_CONTEXT.md`.
-> 3. Fix the issue using a sustainable approach. If an architectural refactor is required for a permanent fix, please propose it first."
-
----
-
-## 🔄 4. Context Synchronization
-Use this at the end of a session or after significant structural changes.
-
-> "I have completed [Task/Feature]. Please update the **`PROJECT_CONTEXT.md`** file to reflect the latest state of the project, including new files created, technical decisions made, and current progress status."
+# Prompt Recipes
+
+Use these prompts after `thachvd-kit init` when you want the AI agent to refine project rules.
+
+## Initial Refinement
+
+```text
+Read AGENTS.md and all files under .agent/docs/.
+Scan the current repository.
+Update .agent/docs/project.md, .agent/docs/architecture.md, and .agent/docs/conventions.md with factual project-specific rules.
+Do not implement product code.
+Remove TODO: refine items only when you have real evidence from the codebase.
+```
+
+## Before A Feature
+
+```text
+Read AGENTS.md and .agent/docs/workflow.md.
+Check whether .agent/docs/architecture.md and .agent/docs/conventions.md are accurate for this task.
+If they are stale, update the relevant docs first.
+Then define success criteria, implement the smallest coherent change, and verify.
+```
+
+## After A Task
+
+```text
+Review the files changed in this task.
+If stack, architecture, conventions, commands, or workflow changed, update the relevant .agent/docs/*.md file.
+Summarize verification evidence before claiming done.
+```

package/kit/README.md

@@ -1,33 +1,29 @@
-# 🛡️ Cross-Platform Project Kit
-
-This toolkit helps you build high-quality, modular, and performance-optimized applications by leveraging AI agents with a context-first approach across Antigravity, Claude Code, and Codex-compatible editors.
-
----
-
-## 🚀 How to Use
-
-### 1. Initialization (Clone & Use)
-- Clone this repository.
-- Update project metadata (e.g., `package.json`).
-- Rename and fill out `PROJECT_CONTEXT.template.md` as `PROJECT_CONTEXT.md` in the root directory.
-
-### 2. Working with AI Agents
-- Always use the templates provided in `kit/PROMPT_RECIPE.md`.
-- Ensure the Agent reads and updates `PROJECT_CONTEXT.md`.
-- Use `CLAUDE.md` for Claude Code and `AGENTS.md` for Codex when generating project-specific entry files.
-- Enforce file splitting rules (e.g., Max 250 lines) to maintain a clean codebase.
-
-### 3. Proposed Structure
-- `.agent/rules/GEMINI.md`: Core behavioral rules and protocols.
-- `.agent/kit/`: Manuals and templates for project management.
-- `PROJECT_CONTEXT.md`: (Manual creation required) The active map of the current project.
-
-## 💎 Golden Rules
-1. **Context is King:** Never let the Agent work without a clear Ground Truth.
-2. **Architecture First:** Design the structure before writing any implementation code.
-3. **Keep it Small:** Small files are easier for AI to understand, modify, and keep in context.
-4. **Self-Documenting:** The Agent is responsible for maintaining the project documentation.
-
----
-
-*Powered by thachvd-kit.*
+# thachvd-kit Kit
+
+This kit keeps AI coding behavior consistent across Codex, Antigravity, and Claude Code.
+
+## Entry Files
+
+- `AGENTS.md`: shared cross-agent instructions.
+- `CLAUDE.md`: Claude Code entry file that imports `AGENTS.md`.
+- `GEMINI.md`: Antigravity entry file that points to `AGENTS.md`.
+
+## Shared Docs
+
+Project-specific knowledge belongs under `.agent/docs/`:
+
+- `project.md`: stack, commands, tools, routing, and scan evidence.
+- `architecture.md`: codebase structure, entry points, and boundaries.
+- `conventions.md`: naming, formatting, testing, API, state, and styling patterns.
+- `workflow.md`: repeatable task flow.
+
+Agents should update these docs when they discover real project facts. Keep root entry files short.
+
+## Local Kit
+
+- `.agent/agents/`: specialist agent guidance.
+- `.agent/skills/`: reusable capability instructions.
+- `.agent/workflows/`: task workflows.
+- `.agent/rules/GEMINI.md`: Antigravity-compatible mirror rules.
+
+Powered by thachvd-kit.

package/package.json

@@ -1,51 +1,51 @@
-{
-    "name": "thachvd-kit",
-    "version": "1.0.14",
-    "description": "Project context bootstrap kit for Antigravity, Claude Code, and Codex",
-    "bin": {
-        "thachvd-kit": "./bin/cli.js"
-    },
-    "files": [
-        "agents",
-        "bin",
-        "kit",
-        "rules",
-        "scripts",
-        "skills",
-        "workflows",
-        "README.md",
-        "LICENSE",
-        "PROJECT_CONTEXT.template.md"
-    ],
-    "preferGlobal": true,
-    "engines": {
-        "node": ">=16.7"
-    },
-    "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1",
-        "release:patch": "npm version patch",
-        "release:dry-run": "npm pack --dry-run",
-        "release:publish": "npm publish"
-    },
-    "keywords": [
-        "ai",
-        "agent",
-        "claude",
-        "antigravity",
-        "codex"
-    ],
-    "author": "thachvd",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/holdon1996/thachvd-kit.git"
-    },
-    "homepage": "https://github.com/holdon1996/thachvd-kit",
-    "bugs": {
-        "url": "https://github.com/holdon1996/thachvd-kit/issues"
-    },
-    "dependencies": {
-        "picocolors": "^1.0.0",
-        "prompts": "^2.4.2"
-    }
-}
+{
+    "name": "thachvd-kit",
+    "version": "1.0.16",
+    "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
+    "bin": {
+        "thachvd-kit": "./bin/cli.js"
+    },
+    "files": [
+        ".agent",
+        "agents",
+        "bin",
+        "kit",
+        "rules",
+        "scripts",
+        "skills",
+        "workflows",
+        "README.md",
+        "LICENSE"
+    ],
+    "preferGlobal": true,
+    "engines": {
+        "node": ">=16.7"
+    },
+    "scripts": {
+        "test": "node test/cli.test.js",
+        "release:patch": "npm version patch",
+        "release:dry-run": "npm pack --dry-run",
+        "release:publish": "npm publish"
+    },
+    "keywords": [
+        "ai",
+        "agent",
+        "claude",
+        "antigravity",
+        "codex"
+    ],
+    "author": "thachvd",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/holdon1996/thachvd-kit.git"
+    },
+    "homepage": "https://github.com/holdon1996/thachvd-kit",
+    "bugs": {
+        "url": "https://github.com/holdon1996/thachvd-kit/issues"
+    },
+    "dependencies": {
+        "picocolors": "^1.0.0",
+        "prompts": "^2.4.2"
+    }
+}

package/rules/GEMINI.md

@@ -1,209 +1,45 @@
----
-trigger: always_on
----
-
-# GEMINI.md — Universal Agent Kit
-
-> Cross-platform agent protocol. Works with: Antigravity · Claude Code · Codex · OpenCode
-
----
-
-## MANDATORY FIRST ACTION
-
-**At session start — before anything else:**
+---
+trigger: always_on
+---
 
-```
-1. Read PROJECT_CONTEXT.md (if exists) → load stack, agents, constraints
-2. If missing → run @[skills/project-onboarding] to create it
-3. Read PROJECT_CONTEXT context.status and context.needs_ai_refinement
-4. If needs_ai_refinement = true → scan project with AI, update PROJECT_CONTEXT.md, set status=refined and needs_ai_refinement=false
-5. Confirm: "Context loaded: [Project Name] | Stack: [Stack] | Ready."
-```
-
-> All routing decisions below depend on PROJECT_CONTEXT.md.
-> Without it, ask user to run: `thachvd-kit init`
-> Baseline context must be refined once when `context.needs_ai_refinement = true`.
-
----
-
-## STEP 1 — CLASSIFY REQUEST
-
-| Type | Triggers | Action |
-|------|----------|--------|
-| **QUESTION** | "what", "how", "explain", "why" | Direct answer |
-| **SURVEY** | "analyze", "list", "overview", "check" | Analysis only, no code |
-| **SIMPLE FIX** | "fix", "add", "change" (single file) | Inline edit |
-| **BUILD** | "build", "create", "implement", "refactor" | Agent + `{task-slug}.md` |
-| **DESIGN/UI** | "design", "UI", "page", "dashboard" | Agent + `{task-slug}.md` |
-
----
-
-## STEP 2 — AUTO-SELECT AGENT
-
-**Protocol:**
-1. Read `stack.primary_language` and `stack.frameworks` from PROJECT_CONTEXT.md
-2. Match to agent table below
-3. Announce before responding:
-
-```
-🤖 Applying knowledge of `@[agent-name]`...
-```
-
-### Agent Routing Table
-
-| Domain | Agent | Skills to Load |
-|--------|-------|---------------|
-| Web frontend (any framework) | `frontend-specialist` | `frontend-design` + framework skill from PROJECT_CONTEXT |
-| Backend API (any language) | `backend-specialist` | language skill + `api-design` |
-| Database / Schema | `database-architect` | `database-design` |
-| Mobile / Desktop (Tauri, RN, Flutter) | `mobile-developer` | platform skill from PROJECT_CONTEXT |
-| DevOps / Cloud / CI | `devops-engineer` | `docker-patterns`, `deployment-procedures` |
-| Security audit | `security-auditor` | `vulnerability-scanner` |
-| Debug / RCA | `debugger` | `systematic-debugging` |
-| Planning / Discovery | `project-planner` | `brainstorming`, `plan-writing` |
-| Multi-domain | `orchestrator` | `dispatching-parallel-agents` |
-
-**Framework-specific skill mapping** (reference PROJECT_CONTEXT.stack):
-
-| Framework/Language | Load Skill |
-|-------------------|-----------|
-| Vue | `frontend-design` (+ Vue-specific if available) |
-| React | `react-frontend` |
-| Next.js | `nextjs-react-expert` |
-| Laravel | `laravel-patterns` + `laravel-security` |
-| Node.js | `nodejs-best-practices` |
-| Python | `python-patterns` |
-| Go | `golang-patterns` |
-| Rust | `rust-pro` |
-| Tauri | `desktop-design` + `rust-pro` |
-| Docker | `docker-patterns` |
-
-> If stack not in mapping → use agent's general skill set + `clean-code`.
-
-**MANDATORY checklist before any code:**
-- [ ] Agent identified from PROJECT_CONTEXT.md stack?
-- [ ] Agent `.md` file read/recalled?
-- [ ] Announcement `🤖 Applying knowledge of @[agent]...` written?
-
-> 🔴 Code without announcement = **PROTOCOL VIOLATION**
-
----
-
-## STEP 3 — SOCRATIC GATE
-
-**Trigger: BUILD or DESIGN/UI requests only**
-
-| Scenario | Action |
-|----------|--------|
-| New feature / greenfield | Ask **3 questions**: Purpose · Users · Must-have vs Nice-to-have |
-| Code edit / bug fix | Confirm scope + 1 impact question |
-| Vague request | Ask Purpose + Constraints |
-| User gave full spec | **Proceed immediately** |
-| User says "proceed" / "just do it" | **DO IT — no more questions** |
-
-**Rules:**
-- Max 3 questions at once
-- Never ask edge case questions after user already answered
-- Reference `@[skills/brainstorming]` for question format
-
----
-
-## UNIVERSAL RULES (Always Active)
-
-### Language
-- Respond in user's language (auto-detect from prompt)
-- Code comments/variables always in English
-
-### Code Quality
-- `@[skills/clean-code]` applies to ALL code, ALL languages
-- Tests mandatory: Unit > Integration > E2E
-- `@[skills/verification-before-completion]` before claiming "done"
-
-### File Changes
-- Identify dependent files before modifying
-- Update ALL affected files together
-
----
-
-## EXECUTION WORKFLOW
-
-**BUILD tasks — 7-step flow:**
-
-```
-1. brainstorming           → Clarify (Socratic Gate)
-2. plan-writing            → Create {task-slug}.md
-3. using-git-worktrees     → Isolated workspace
-4. subagent-driven-development → Implement + 2-stage review
-5. requesting-code-review  → After each major task
-6. verification-before-completion → Before claiming done
-7. finishing-a-development-branch → Merge / PR / keep
-```
-
-**SIMPLE FIX:** Skip to step 4, no worktree needed.
-
----
-
-## MODE BEHAVIOR
-
-| Mode | Behavior |
-|------|----------|
-| **plan** | Analysis → Planning → Architecture → NO CODE until confirmed |
-| **ask** | Questions and analysis only |
-| **edit** | Execute. Multi-file → create `{task-slug}.md`. Single-file → proceed. |
-
----
-
-## FINAL CHECK
-
-**Trigger:** "final check", "deploy check", "kiểm tra cuối", "done?"
-
-```bash
-python scripts/checklist.py .
-```
-
-Priority: Security → Lint → Tests → UX → SEO
-
----
-
-## PATHS
-
-```
-agents/     → agents/{agent}.md
-skills/     → skills/{skill}/SKILL.md
-workflows/  → workflows/{command}.md
-scripts/    → scripts/init.py, checklist.py, verify_all.py
-```
-
----
-
-## QUICK SKILL REFERENCE
-
-| Need | Skill |
-|------|-------|
-| Clean code (any lang) | `clean-code` |
-| Plan a task | `plan-writing` → `executing-plans` |
-| Parallel agents | `dispatching-parallel-agents` |
-| Code review | `requesting-code-review` / `receiving-code-review` |
-| Git isolation | `using-git-worktrees` |
-| Agent-based dev | `subagent-driven-development` |
-| Verify done | `verification-before-completion` |
-| Finish branch | `finishing-a-development-branch` |
-| Write new skill | `writing-skills` |
-| API design | `api-design` |
-| Docker | `docker-patterns` |
-| Laravel | `laravel-patterns`, `laravel-security`, `laravel-tdd` |
-| Go | `golang-patterns`, `golang-testing` |
-| Debugging | `systematic-debugging` |
-| Security | `vulnerability-scanner` |
-
----
-
-## CROSS-PLATFORM NOTES
-
-| Platform | Rules File | Skills Dir | Workflows |
-|----------|-----------|-----------|-----------|
-| **Antigravity** | `rules/GEMINI.md` (this file) | `skills/` | `workflows/` |
-| **Claude Code** | `CLAUDE.md` at project root | `.agent/skills/` | `.agent/workflows/` |
-| **Codex / OpenCode** | `AGENTS.md` at project root | `.agent/skills/` | `.agent/workflows/` |
+# GEMINI.md
 
-> Run `thachvd-kit init` to generate project context and platform entry files automatically.
+Antigravity-compatible entry rules for thachvd-kit projects.
+
+## Startup
+
+1. Read `AGENTS.md` at the project root.
+2. Read `.agent/docs/project.md` for stack, commands, and routing.
+3. Read `.agent/docs/workflow.md` before editing.
+4. Read `.agent/docs/architecture.md` and `.agent/docs/conventions.md` before planning non-trivial code changes.
+5. If any `.agent/docs/*.md` file contains `TODO: refine`, update that doc from the real code before product code changes.
+
+## Routing
+
+- Frontend/UI: `.agent/agents/frontend-specialist.md`
+- Backend/API: `.agent/agents/backend-specialist.md`
+- Database/schema: `.agent/agents/database-architect.md`
+- Mobile/desktop: `.agent/agents/mobile-developer.md`
+- DevOps/CI/deploy: `.agent/agents/devops-engineer.md`
+- Debug/RCA: `.agent/agents/debugger.md`
+- Security: `.agent/agents/security-auditor.md`
+- Multi-domain: `.agent/agents/orchestrator.md`
+
+Load only the agent, skill, or workflow files relevant to the current task.
+
+## Execution
+
+- Questions and analysis: answer directly; do not edit code.
+- Simple fix: inspect dependencies, make the smallest change, verify.
+- Feature or refactor: state assumptions, define success criteria, plan, implement, verify.
+- UI work: use relevant frontend design skills before editing.
+- Security or deploy work: run the matching checklist before claiming done.
+
+## Standards
+
+- Respond in the user's language.
+- Keep code, identifiers, and code comments in English.
+- Prefer existing project patterns over new abstractions.
+- Keep changes surgical.
+- Tests or equivalent verification are mandatory.
+- Update `.agent/docs/*` when stack, architecture, workflow, or conventions change.

package/skills/desktop-design/SKILL.md

@@ -1,25 +1,25 @@
----
-name: desktop-design
-description: Desktop and cross-platform app design guidance for Tauri and similar desktop shells. Use when building desktop-first interfaces, windowed workflows, keyboard-heavy UX, or cross-platform desktop UI behavior.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
----
-
-# Desktop Design
-
-This skill covers desktop-first product thinking where `mobile-design` is the wrong default.
-
-Use it for Tauri and other desktop-oriented apps with window management, keyboard shortcuts, dense layouts, or multi-panel workflows.
-
-## Guidance
-
-- Design for pointer + keyboard, not touch-first.
-- Use information density deliberately; desktop screens can support richer sidebars and multi-column layouts.
-- Respect platform conventions for menus, shortcuts, dialogs, file pickers, and drag/drop.
-- Assume resizing, multiple windows, and long-running sessions are normal.
-- Pair with `rust-pro` for Tauri backend/native concerns and `frontend-design` for UI execution.
-
-## Related Skills
-
-- `mobile-design` for touch-first mobile products
-- `frontend-design` for visual and interaction design
-- `rust-pro` for Rust and Tauri implementation details
+---
+name: desktop-design
+description: Desktop and cross-platform app design guidance for Tauri and similar desktop shells. Use when building desktop-first interfaces, windowed workflows, keyboard-heavy UX, or cross-platform desktop UI behavior.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Desktop Design
+
+This skill covers desktop-first product thinking where `mobile-design` is the wrong default.
+
+Use it for Tauri and other desktop-oriented apps with window management, keyboard shortcuts, dense layouts, or multi-panel workflows.
+
+## Guidance
+
+- Design for pointer + keyboard, not touch-first.
+- Use information density deliberately; desktop screens can support richer sidebars and multi-column layouts.
+- Respect platform conventions for menus, shortcuts, dialogs, file pickers, and drag/drop.
+- Assume resizing, multiple windows, and long-running sessions are normal.
+- Pair with `rust-pro` for Tauri backend/native concerns and `frontend-design` for UI execution.
+
+## Related Skills
+
+- `mobile-design` for touch-first mobile products
+- `frontend-design` for visual and interaction design
+- `rust-pro` for Rust and Tauri implementation details

package/skills/project-onboarding/SKILL.md

@@ -1,62 +1,42 @@
----
-name: project-onboarding
-description: Skill for project reconnaissance and Ground Truth establishment. Automatically scans project structure, tech stack, and logic to create or update PROJECT_CONTEXT.md.
-allowed-tools: list_dir, grep_search, find_by_name, view_file, write_to_file
----
-
-# Project Onboarding Skill
-
-> Establish a Ground Truth map for any project before writing code.
-
----
-
-## 🎯 Objectives
-- **Reconnaissance:** Understand the directory structure, technology stack, and core business logic.
-- **Ground Truth:** Create `PROJECT_CONTEXT.md` to serve as the project's primary reference.
-- **Continuity:** Ensure all future sessions have a map to follow.
-
----
-
-## 📑 Process
-
-1. **Scan Filesystem:**
-   - Run `list_dir` on root.
-   - Run `find_by_name` for configuration files (`package.json`, `tsconfig.json`, `tailwind.config.js`, etc.).
-2. **Identify Tech Stack:**
-   - Detect frameworks (React, Next.js, Vite, etc.).
-   - Detect database/storage (SQL, NoSQL, client-side DB).
-   - Detect styling and UI libraries.
-3. **Analyze Structure:**
-   - Identify where pages, components, logic, and state management live.
-4. **Identify Core Logic:**
-   - `grep` for main keywords (e.g., patient, pharmacy, etc.) to find business rules.
-5. **Create/Update Map:**
-   - Generate `PROJECT_CONTEXT.md` in root using the `PROJECT_CONTEXT.template.md` as a guide.
-
----
-
-## ✅ Onboarding Checklist
-
-Before completing onboarding:
-
-- [ ] **Scanned root directory?**
-- [ ] **Identified Frontend/Backend stack?**
-- [ ] **Mapped primary folder structure?**
-- [ ] **Found core business logic entry points?**
-- [ ] **Created/Updated PROJECT_CONTEXT.md?**
-- [ ] **Stated: "Ground Truth identified/established. Ready to proceed."?**
-
----
-
-## ❌ Anti-Patterns
-
-**DON'T:**
-- Skip onboarding for "simple" fixes.
-- Assume structure based on generic templates.
-- Start writing code before `PROJECT_CONTEXT.md` exists.
-- Leave the context file empty or vague.
-
-**DO:**
-- Perform deep directory analysis.
-- Read core configuration files.
-- Document any project-specific constraints found in existing code.
+---
+name: project-onboarding
+description: Scan the repository and refine `.agent/docs/*` so all supported AI tools share accurate project rules.
+---
+
+# Project Onboarding
+
+Use this skill when a project has just run `thachvd-kit init`, when `.agent/docs/*` contains `TODO: refine`, or when the stack/architecture has changed.
+
+## Goal
+
+Create or update the shared project docs used by Codex, Antigravity, and Claude Code:
+
+- `.agent/docs/project.md`
+- `.agent/docs/architecture.md`
+- `.agent/docs/conventions.md`
+- `.agent/docs/workflow.md`
+
+Do not create a legacy root context file.
+
+## Process
+
+1. Read `AGENTS.md`.
+2. Inspect repository structure, package/build config, test config, entry points, and representative source files.
+3. Update `.agent/docs/project.md` with stack, app root, commands, test/lint tooling, and routing.
+4. Update `.agent/docs/architecture.md` with major directories, entry points, boundaries, and important decisions.
+5. Update `.agent/docs/conventions.md` with real naming, formatting, API, state, styling, and testing patterns.
+6. Update `.agent/docs/workflow.md` only when the repository needs project-specific workflow steps.
+
+## Rules
+
+- Keep docs concise and factual.
+- Mark unknowns as `TODO: refine` only when the codebase does not provide evidence.
+- Do not implement product code during onboarding.
+- Do not overwrite unrelated user-maintained notes.
+
+## Completion Checklist
+
+- [ ] `.agent/docs/project.md` reflects actual stack and commands.
+- [ ] `.agent/docs/architecture.md` maps the current codebase.
+- [ ] `.agent/docs/conventions.md` captures observed patterns.
+- [ ] `.agent/docs/workflow.md` has the task flow agents should follow.