feat: add .architect/ project mapping system with architect-indexer agent and Docker containerization
- Add .architect/ directory structure (10 template files) as project brain for agent orientation - Add architect-indexer agent that scans codebase and generates structured architecture docs - Add Docker containerization: Dockerfile.architect-indexer, docker-compose.architect.yml - Add TypeScript project-mapper module with staleness detection and context injection - Add /index-project command, architect-first-contact rule, project-mapping skill - Integrate orchestrator first-contact check: triggers indexing before any task delegation - Add npm arch:* scripts for Docker-based indexing workflow - Register agent in capability-index.yaml and AGENTS.md
This commit is contained in:
¨NW¨
159
.kilo/agents/architect-indexer.md
Normal file
159
.kilo/agents/architect-indexer.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
description: Indexes and maps project codebase architecture into .architect/ directory. Creates and maintains structured documentation of entities, APIs, DB schema, file graphs, and conventions.
|
||||
mode: subagent
|
||||
model: ollama-cloud/glm-5.1
|
||||
variant: thinking
|
||||
color: "#10B981"
|
||||
permission:
|
||||
read: allow
|
||||
edit: allow
|
||||
write: allow
|
||||
bash: allow
|
||||
glob: allow
|
||||
grep: allow
|
||||
task:
|
||||
"*": deny
|
||||
"system-analyst": allow
|
||||
"orchestrator": allow
|
||||
---
|
||||
|
||||
# Architect Indexer
|
||||
|
||||
## Role
|
||||
Project cartographer. Scans the codebase and produces a structured, navigable map in `.architect/` that all agents can reference for orientation.
|
||||
|
||||
## Execution Environment (CRITICAL)
|
||||
**All indexing runs inside a Docker container.** Never run npm/npx/bun/node on the host machine.
|
||||
|
||||
```bash
|
||||
# Build & run
|
||||
docker compose -f docker/docker-compose.architect.yml build
|
||||
docker compose -f docker/docker-compose.architect.yml run --rm architect-indexer
|
||||
|
||||
# Or via npm shortcuts
|
||||
npm run arch:build && npm run arch:index
|
||||
```
|
||||
|
||||
## When Invoked
|
||||
- Orchestrator detects missing or stale `.architect/state.json` on first contact with a project
|
||||
- After structural changes (file add/remove, new module, new migration, new endpoint)
|
||||
- On `/index-project` command
|
||||
- Incrementally after `lead-developer` or `the-fixer` complete tasks that modify project structure
|
||||
|
||||
## Indexing Protocol
|
||||
|
||||
### Step 1: Detect Project Type
|
||||
```
|
||||
1. Check for package.json → Node.js/TypeScript project
|
||||
2. Check for composer.json → PHP project
|
||||
3. Check for go.mod → Go project
|
||||
4. Check for pubspec.yaml → Flutter/Dart project
|
||||
5. Check for requirements.txt/pyproject.toml → Python project
|
||||
6. If none found → Generic project
|
||||
```
|
||||
|
||||
### Step 2: Full Index (first run or staleness > 24h)
|
||||
1. Scan directory structure → `architecture/overview.md`
|
||||
2. Parse dependency files → `tech-stack/stack.md`
|
||||
3. Find all models/entities → `entities/entities.md`
|
||||
4. Find all DB migrations/schemas → `db-schema/schema.md`
|
||||
5. Find all API routes/controllers → `api-surface/endpoints.md`
|
||||
6. Detect lint/format configs → `conventions/conventions.md`
|
||||
7. Build import graph → `maps/file-graph.json`
|
||||
8. Build module graph → `maps/module-graph.json`
|
||||
9. Populate `project.json` with metadata
|
||||
10. Update `state.json` with hashes and timestamp
|
||||
|
||||
### Step 3: Incremental Update (on file change)
|
||||
1. Compare `state.json` file hashes with current files
|
||||
2. Determine which sections are affected:
|
||||
- New/removed file → update `file-graph.json`, `module-graph.json`
|
||||
- New dependency → update `tech-stack/stack.md`, run full reindex
|
||||
- New migration → update `db-schema/schema.md`
|
||||
- New model/entity → update `entities/entities.md`
|
||||
- New endpoint → update `api-surface/endpoints.md`
|
||||
3. Only regenerate affected sections
|
||||
4. Update `state.json` hashes
|
||||
|
||||
### Step 4: Validate
|
||||
1. Check README.md navigation links still valid
|
||||
2. Verify project.json fields are non-empty
|
||||
3. Confirm no circular dependencies in module graph
|
||||
4. Update README.md quick status table
|
||||
|
||||
## Output Format
|
||||
|
||||
### project.json Structure
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"project": {
|
||||
"name": "from package.json or directory name",
|
||||
"type": "laravel|nextjs|express|go-api|flutter|django|fastapi|generic",
|
||||
"framework": "framework name and version",
|
||||
"language": "primary language",
|
||||
"description": "from package.json description or README",
|
||||
"repository": "from git remote",
|
||||
"entry_points": ["main entry files"],
|
||||
"rootDir": "project root"
|
||||
},
|
||||
"structure": { "directories": {}, "key_files": {} },
|
||||
"tech_stack": { "languages": [], "frameworks": [], "databases": [] },
|
||||
"modules": [{ "name": "", "path": "", "exports": [], "imports": [] }],
|
||||
"entities": [{ "name": "", "module": "", "fields": [], "relations": [] }],
|
||||
"api_endpoints": [{ "method": "", "path": "", "controller": "", "auth": "" }],
|
||||
"db_tables": [{ "name": "", "columns": [], "indexes": [], "foreign_keys": [] }],
|
||||
"conventions": { "naming": {}, "patterns": [], "forbidden": [] }
|
||||
}
|
||||
```
|
||||
|
||||
### state.json Section Hashes
|
||||
For each section, store a hash of the source files used to generate it:
|
||||
```json
|
||||
{
|
||||
"sections": {
|
||||
"entities": {
|
||||
"last_updated": "2026-04-19T12:00:00Z",
|
||||
"file_hash": "sha256:abc...",
|
||||
"status": "fresh|stale|missing"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Staleness Detection
|
||||
|
||||
A section is **stale** if:
|
||||
1. Any source file it was generated from has changed (hash mismatch)
|
||||
2. More than 24 hours since last update
|
||||
3. New files were added to directories the section covers
|
||||
|
||||
A section is **missing** if:
|
||||
1. It has never been generated
|
||||
2. Its output file doesn't exist
|
||||
|
||||
## File Size Limits
|
||||
|
||||
| Output File | Max Lines | If Exceeded |
|
||||
|-------------|-----------|-------------|
|
||||
| overview.md | 200 | Split into multiple files |
|
||||
| entities.md | 300 | Group by module |
|
||||
| schema.md | 300 | Split by table group |
|
||||
| endpoints.md | 200 | Split by API version |
|
||||
| conventions.md | 150 | Link to external docs |
|
||||
| stack.md | 100 | Summarize, link to lock files |
|
||||
| file-graph.json | 2000 | Compress edges |
|
||||
| module-graph.json | 500 | Aggregate leaf modules |
|
||||
|
||||
## Conventions
|
||||
- Use `<gitea-commenting required="true" />` when posting indexing results
|
||||
- Post a comment on the issue: "## 🏗 architect-indexer completed — `.architect/` indexed N files, M modules, K endpoints"
|
||||
- Never modify source code — only write to `.architect/`
|
||||
- Never delete sections — only update or add new ones
|
||||
|
||||
## Handoff
|
||||
After indexing, return control to `orchestrator` with:
|
||||
- Summary of what was indexed
|
||||
- Number of files, modules, entities, endpoints found
|
||||
- Any circular dependencies or architectural violations detected
|
||||
- List of sections that are still empty (no data found)
|
||||
@@ -43,6 +43,7 @@ permission:
|
||||
"agent-architect": allow
|
||||
"php-developer": allow
|
||||
"python-developer": allow
|
||||
"architect-indexer": allow
|
||||
---
|
||||
|
||||
# Orchestrator
|
||||
@@ -52,6 +53,11 @@ Task dispatcher and state machine manager. Route by issue status; enforce workfl
|
||||
|
||||
## Behavior
|
||||
- Route by status: new→history-miner, researching→system-analyst, testing→sdet-engineer, implementing→lead-developer, fail→the-fixer
|
||||
- **FIRST CONTACT**: Before any task delegation, check `.architect/state.json`:
|
||||
- If missing or `status === 'not_indexed'` → delegate `architect-indexer` FIRST
|
||||
- If stale (any section `status === 'stale'`) → delegate `architect-indexer` incrementally
|
||||
- If fresh → proceed with normal routing, read relevant `.architect/` sections for context
|
||||
- After `lead-developer` or `the-fixer` complete tasks that add/remove files → mark affected `.architect/` sections as stale
|
||||
- Check blockers before routing; suspend if dependencies unmet
|
||||
- Only you authorize release-manager after evaluator confirmation
|
||||
- Comms: "To: [Agent]. Task: [essence]. Context: [file ref]"
|
||||
@@ -64,6 +70,7 @@ Task dispatcher and state machine manager. Route by issue status; enforce workfl
|
||||
| Agent | When |
|
||||
|-------|------|
|
||||
| requirement-refiner | New vague request: refine requirements |
|
||||
| architect-indexer | First contact or stale `.architect/`: index project |
|
||||
| history-miner | New issue: check duplicates |
|
||||
| system-analyst | Researching: design specifications |
|
||||
| sdet-engineer | Designing: write failing tests |
|
||||
|
||||
@@ -517,6 +517,7 @@ agents:
|
||||
- reflector
|
||||
- memory-manager
|
||||
- agent-architect
|
||||
- architect-indexer
|
||||
|
||||
release-manager:
|
||||
capabilities:
|
||||
@@ -741,6 +742,42 @@ agents:
|
||||
mode: subagent
|
||||
delegates_to: []
|
||||
|
||||
# Project Mapping
|
||||
architect-indexer:
|
||||
capabilities:
|
||||
- codebase_indexing
|
||||
- project_mapping
|
||||
- architecture_documentation
|
||||
- dependency_analysis
|
||||
- entity_extraction
|
||||
- api_surface_discovery
|
||||
- convention_detection
|
||||
- staleness_detection
|
||||
receives:
|
||||
- project_root_directory
|
||||
- stale_sections_list
|
||||
produces:
|
||||
- .architect/state.json
|
||||
- .architect/project.json
|
||||
- .architect/README.md
|
||||
- architecture_overview
|
||||
- dependency_graph
|
||||
- entity_documentation
|
||||
- db_schema_documentation
|
||||
- api_surface_documentation
|
||||
- convention_documentation
|
||||
- file_graph
|
||||
- module_graph
|
||||
forbidden:
|
||||
- code_changes
|
||||
- implementation
|
||||
model: ollama-cloud/glm-5.1
|
||||
variant: thinking
|
||||
mode: subagent
|
||||
delegates_to:
|
||||
- system-analyst
|
||||
- orchestrator
|
||||
|
||||
# Capability Routing Map
|
||||
capability_routing:
|
||||
code_writing: lead-developer
|
||||
@@ -806,6 +843,14 @@ agents:
|
||||
go_concurrent_programming: go-developer
|
||||
go_authentication: go-developer
|
||||
go_microservices: go-developer
|
||||
# Project Mapping
|
||||
codebase_indexing: architect-indexer
|
||||
project_mapping: architect-indexer
|
||||
architecture_documentation: architect-indexer
|
||||
dependency_analysis: architect-indexer
|
||||
entity_extraction: architect-indexer
|
||||
api_surface_discovery: architect-indexer
|
||||
convention_detection: architect-indexer
|
||||
|
||||
# Parallelizable Tasks
|
||||
parallel_groups:
|
||||
|
||||
239
.kilo/commands/index-project.md
Normal file
239
.kilo/commands/index-project.md
Normal file
@@ -0,0 +1,239 @@
|
||||
---
|
||||
description: Index the project codebase into .architect/ directory for agent navigation and orientation
|
||||
---
|
||||
|
||||
# Index Project Command
|
||||
|
||||
You are the `architect-indexer` agent. Your task is to scan the project codebase and populate the `.architect/` directory with structured, navigable documentation.
|
||||
|
||||
## Docker Execution (REQUIRED)
|
||||
|
||||
**All indexing runs inside a Docker container.** Never run `npm`, `npx`, `bun`, or `node` directly on the host machine.
|
||||
|
||||
### Build & Run
|
||||
|
||||
```bash
|
||||
# Build the indexer image (first time or after Dockerfile changes)
|
||||
docker compose -f docker/docker-compose.architect.yml build
|
||||
|
||||
# Full index (first run or staleness > 24h)
|
||||
docker compose -f docker/docker-compose.architect.yml run --rm architect-indexer
|
||||
|
||||
# Incremental update (only stale sections)
|
||||
docker compose -f docker/docker-compose.architect.yml run --rm architect-indexer --mode incremental
|
||||
|
||||
# Full index with specific sections only
|
||||
docker compose -f docker/docker-compose.architect.yml run --rm architect-indexer --mode incremental --sections entities,api_surface
|
||||
```
|
||||
|
||||
### Quick NPM Scripts (Host → Docker)
|
||||
|
||||
```bash
|
||||
npm run arch:build # Build Docker image
|
||||
npm run arch:index # Run full index in container
|
||||
npm run arch:index:full # Force full index
|
||||
npm run arch:index:incremental # Only stale sections
|
||||
npm run arch:status # Check container status
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Detect & Scan
|
||||
|
||||
1. **Detect project type** by checking for:
|
||||
- `package.json` → Node.js / TypeScript
|
||||
- `composer.json` → PHP / Laravel / Symfony / WordPress
|
||||
- `go.mod` → Go
|
||||
- `pubspec.yaml` → Flutter / Dart
|
||||
- `requirements.txt` or `pyproject.toml` → Python
|
||||
- `Cargo.toml` → Rust
|
||||
- None found → Generic
|
||||
|
||||
2. **Check `.architect/state.json`** for staleness:
|
||||
- If `status === "not_indexed"` → Full index
|
||||
- If `last_full_index` older than 24h → Full index
|
||||
- If only specific sections stale → Incremental update
|
||||
|
||||
3. **Scan directory tree** using `glob` tools
|
||||
|
||||
### Phase 2: Full Index
|
||||
|
||||
Execute each step as an atomic subtask:
|
||||
|
||||
#### 2a. Project Metadata → `project.json`
|
||||
```bash
|
||||
# Scan for project config files
|
||||
Read: package.json, composer.json, go.mod, pubspec.yaml, pyproject.toml
|
||||
# Extract: name, type, framework, language, description, entry points
|
||||
```
|
||||
|
||||
Populate:
|
||||
- `project.name`
|
||||
- `project.type`
|
||||
- `project.framework`
|
||||
- `project.language`
|
||||
- `project.description`
|
||||
- `project.entry_points`
|
||||
- `project.repository` (from git remote)
|
||||
- `structure.directories` (key dirs only)
|
||||
- `structure.key_files` (config, entry points)
|
||||
- `tech_stack` (from dependencies)
|
||||
|
||||
#### 2b. Architecture Overview → `architecture/overview.md`
|
||||
- Identify architectural pattern (layered, clean, MVC, etc.)
|
||||
- Map directory structure to layers
|
||||
- Identify module boundaries
|
||||
- List external services
|
||||
- Draw simple ASCII diagram
|
||||
|
||||
#### 2c. Dependency Graph → `architecture/dependency-graph.md`
|
||||
- Parse import/require statements across all source files
|
||||
- Build module-to-module dependency map
|
||||
- Detect circular dependencies
|
||||
- List external packages with versions
|
||||
|
||||
#### 2d. Entities → `entities/entities.md`
|
||||
- Find all model/entity/domain class files
|
||||
- Extract fields, types, relations
|
||||
- For Laravel: `app/Models/`
|
||||
- For Go: `internal/*/model/`
|
||||
- For Node.js: `src/models/` or `src/entities/`
|
||||
- For Python: `models.py`, `schemas.py`
|
||||
- Document relationships (1:1, 1:N, N:M)
|
||||
|
||||
#### 2e. DB Schema → `db-schema/schema.md`
|
||||
- Find migration files
|
||||
- Parse table definitions, columns, indexes, foreign keys
|
||||
- For Laravel: `database/migrations/`
|
||||
- For Go: migration files
|
||||
- For Node.js: `prisma/schema.prisma` or migration files
|
||||
- For Python: Django migrations or Alembic
|
||||
|
||||
#### 2f. API Surface → `api-surface/endpoints.md`
|
||||
- Find all route/endpoint definitions
|
||||
- For Laravel: `routes/*.php`
|
||||
- For Express: `src/routes/` or route files
|
||||
- For Go: handler registrations
|
||||
- For Python: URL confs or router files
|
||||
- Document: method, path, auth, controller, description
|
||||
|
||||
#### 2g. Conventions → `conventions/conventions.md`
|
||||
- Read eslint/prettier/phpstan/lint configs
|
||||
- Read existing code patterns from a few representative files
|
||||
- Identify naming conventions (files, variables, classes)
|
||||
- Identify architectural patterns (repository, service, etc.)
|
||||
- Check `.kilo/rules/` for project-specific rules
|
||||
|
||||
#### 2h. Tech Stack → `tech-stack/stack.md`
|
||||
- Parse all dependency files
|
||||
- Read versions from lock files
|
||||
- Identify dev tools (linters, formatters, test runners)
|
||||
- Identify infrastructure (Docker, CI configs)
|
||||
|
||||
#### 2i. File Graph → `maps/file-graph.json`
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"generated_at": "ISO timestamp",
|
||||
"root": "project root absolute path",
|
||||
"nodes": {
|
||||
"path/to/file.ts": {
|
||||
"type": "module|script|config|test|migration|style",
|
||||
"imports": ["./other/file"],
|
||||
"exports": ["exportedName"],
|
||||
"size_bytes": 1234,
|
||||
"last_modified": "ISO timestamp"
|
||||
}
|
||||
},
|
||||
"edges": [
|
||||
{ "from": "path/to/file.ts", "to": "./other/file.ts", "type": "import" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 2j. Module Graph → `maps/module-graph.json`
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"generated_at": "ISO timestamp",
|
||||
"modules": [
|
||||
{
|
||||
"name": "module-name",
|
||||
"path": "src/modules/module-name",
|
||||
"type": "feature|shared|core|infra",
|
||||
"imports": ["other-module"],
|
||||
"exports": ["PublicClass", "publicFunction"],
|
||||
"entities": ["EntityName"],
|
||||
"endpoints": 5,
|
||||
"file_count": 12
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Update State
|
||||
|
||||
1. Compute SHA256 hashes of all scanned source files
|
||||
2. Update `state.json`:
|
||||
- `status: "indexed"`
|
||||
- `last_full_index: <ISO timestamp>`
|
||||
- `last_incremental_update: <ISO timestamp>`
|
||||
- `last_file_count: <total files>`
|
||||
- `file_hashes: { <path>: <hash> }`
|
||||
- Update each section's `status` to `"fresh"`, `last_updated`, `file_hash`
|
||||
|
||||
3. Update `README.md` Quick Status table with:
|
||||
- `Last Indexed` timestamp
|
||||
- `Index Version`
|
||||
- `Files Tracked` count
|
||||
- `Modules` count
|
||||
- `Staleness: fresh`
|
||||
|
||||
### Phase 4: Report
|
||||
|
||||
Post a summary comment:
|
||||
|
||||
```markdown
|
||||
## 🏗 architect-indexer completed
|
||||
|
||||
**Files Tracked**: {count}
|
||||
**Modules Found**: {count}
|
||||
**Entities Found**: {count}
|
||||
**Endpoints Found**: {count}
|
||||
**DB Tables Found**: {count}
|
||||
**Circular Dependencies**: {count} (listed if any)
|
||||
|
||||
### Staleness
|
||||
All sections: ✅ fresh
|
||||
|
||||
### Architecture Violations
|
||||
- {any violations found, or "None detected"}
|
||||
```
|
||||
|
||||
## Incremental Update Mode
|
||||
|
||||
When only specific sections are stale:
|
||||
|
||||
1. Check `state.json` for which sections are `stale`
|
||||
2. Only regenerate stale sections
|
||||
3. Update `state.json` with new hashes
|
||||
4. Update README.md status
|
||||
5. Skip sections that are `fresh`
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If `.architect/` directory doesn't exist, create it
|
||||
- If a section has no data (e.g., no DB in frontend project), write "Not applicable for this project type"
|
||||
- If scanning fails partially, mark that section as `error` in `state.json` and continue
|
||||
- Never delete existing sections during incremental updates
|
||||
|
||||
## Token Budget
|
||||
|
||||
| Task | Max Tokens |
|
||||
|------|-----------|
|
||||
| Full index (small project < 50 files) | 10,000 |
|
||||
| Full index (medium project 50-200 files) | 20,000 |
|
||||
| Full index (large project > 200 files) | 30,000 |
|
||||
| Incremental update (1-3 sections) | 5,000 |
|
||||
|
||||
<gitea-commenting required="true" />
|
||||
@@ -21,6 +21,20 @@ You are orchestrating the full agent pipeline for issue #{issue_number}. Execute
|
||||
- Referenced files
|
||||
- Current status label
|
||||
|
||||
### Step 1.5: Check Architect Index
|
||||
|
||||
Before routing any agent, check if `.architect/` is indexed (runs in Docker):
|
||||
|
||||
1. Read `.architect/state.json`
|
||||
2. If missing or `status === 'not_indexed'`:
|
||||
- Run full index in Docker: `docker compose -f docker/docker-compose.architect.yml run --rm architect-indexer`
|
||||
- Wait for indexing to complete before proceeding
|
||||
3. If any section has `status === 'stale'`:
|
||||
- Run incremental in Docker: `docker compose -f docker/docker-compose.architect.yml run --rm architect-indexer --mode incremental`
|
||||
4. If `status === 'indexed'` and all sections fresh:
|
||||
- Read relevant `.architect/` sections based on agent type
|
||||
- Inject context into agent prompt
|
||||
|
||||
## Step 2: Check for Duplicates
|
||||
|
||||
1. Use `grep` to search git history for similar issues:
|
||||
|
||||
97
.kilo/rules/architect-first-contact.md
Normal file
97
.kilo/rules/architect-first-contact.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Architect First-Contact Rules
|
||||
|
||||
When an orchestrator or pipeline starts working on a project, it MUST check the project's `.architect/` directory for orientation before delegating tasks.
|
||||
|
||||
## Mandatory Check
|
||||
|
||||
**All indexing runs in Docker. Never run npm/npx/bun on the host.**
|
||||
|
||||
### Before Any Task Delegation
|
||||
|
||||
```
|
||||
1. Read .architect/state.json
|
||||
2. If file missing or status === 'not_indexed':
|
||||
→ Run: docker compose -f docker/docker-compose.architect.yml run --rm architect-indexer
|
||||
→ WAIT for indexing to complete before routing any other agent
|
||||
3. If any section has status === 'stale':
|
||||
→ Run: docker compose -f docker/docker-compose.architect.yml run --rm architect-indexer --mode incremental
|
||||
→ Proceed with task routing for non-stale sections
|
||||
4. If status === 'indexed' and all sections fresh:
|
||||
→ Proceed with normal routing
|
||||
→ Include relevant .architect/ sections in agent context
|
||||
```
|
||||
|
||||
### Quick Commands
|
||||
|
||||
```bash
|
||||
npm run arch:build # Build Docker image
|
||||
npm run arch:index # Run full index in container
|
||||
npm run arch:index:full # Force full index
|
||||
npm run arch:index:incremental # Only stale sections
|
||||
npm run arch:status # Check container status
|
||||
```
|
||||
|
||||
### Staleness Thresholds
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| `state.json` missing | Full index required |
|
||||
| `status === 'not_indexed'` | Full index required |
|
||||
| Last full index > 24h ago | Full index recommended |
|
||||
| Any section `status === 'stale'` | Incremental update of stale sections |
|
||||
| All sections `status === 'fresh'` | No index needed, proceed |
|
||||
|
||||
### Post-Task Staleness Marking
|
||||
|
||||
After `lead-developer` or `the-fixer` complete a task:
|
||||
|
||||
```
|
||||
1. Compare task's modified files with .architect/state.json sections
|
||||
2. Mark affected sections as 'stale':
|
||||
- New/removed files → file_graph, module_graph
|
||||
- New dependency → tech_stack (full reindex)
|
||||
- New migration → db_schema
|
||||
- New model/entity → entities
|
||||
- New API endpoint → api_surface
|
||||
- Convention changes → conventions
|
||||
- Structural refactor → architecture_overview, dependency_graph
|
||||
3. Update state.json with stale section markers
|
||||
```
|
||||
|
||||
### Context Injection
|
||||
|
||||
When delegating to any agent, include relevant `.architect/` context:
|
||||
|
||||
| Agent | Sections to Include |
|
||||
|-------|-------------------|
|
||||
| system-analyst | architecture/overview, entities, db-schema, api-surface |
|
||||
| sdet-engineer | api-surface, entities, conventions |
|
||||
| lead-developer | conventions, entities, architecture/overview |
|
||||
| code-skeptic | conventions, architecture/dependency-graph |
|
||||
| the-fixer | conventions, file relevant to bug |
|
||||
| php-developer | conventions, entities, db-schema, api-surface |
|
||||
| python-developer | conventions, entities, db-schema, api-surface |
|
||||
| go-developer | conventions, entities, db-schema, api-surface |
|
||||
| frontend-developer | conventions, api-surface, architecture/overview |
|
||||
| backend-developer | conventions, entities, db-schema, api-surface |
|
||||
|
||||
### Project Type Routing
|
||||
|
||||
Use `.architect/project.json` `project.type` to route language-specific agents:
|
||||
|
||||
| project.type | Primary Agent |
|
||||
|-------------|--------------|
|
||||
| laravel | php-developer |
|
||||
| symfony | php-developer |
|
||||
| wordpress | php-developer |
|
||||
| nextjs | frontend-developer |
|
||||
| express | backend-developer |
|
||||
| go-api | go-developer |
|
||||
| flutter | flutter-developer |
|
||||
| django | python-developer |
|
||||
| fastapi | python-developer |
|
||||
| generic | lead-developer |
|
||||
|
||||
## State File Reference
|
||||
|
||||
See `.kilo/skills/project-mapping/SKILL.md` for full `state.json` schema and `.architect/` structure.
|
||||
203
.kilo/skills/project-mapping/SKILL.md
Normal file
203
.kilo/skills/project-mapping/SKILL.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# Project Mapping Skill
|
||||
|
||||
Scans and indexes project codebase into `.architect/` directory for agent navigation.
|
||||
|
||||
## Purpose
|
||||
|
||||
When agents start working on a project for the first time, they need orientation:
|
||||
- What kind of project is this?
|
||||
- Where are the models, controllers, routes?
|
||||
- What's the tech stack?
|
||||
- What conventions does it follow?
|
||||
- How do modules depend on each other?
|
||||
|
||||
The `.architect/` directory provides this orientation as structured, machine+human-readable files.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
.architect/
|
||||
├── README.md # Navigation index (auto-updated)
|
||||
├── project.json # Machine-readable project metadata
|
||||
├── state.json # Index freshness state (hashes, timestamps)
|
||||
├── architecture/
|
||||
│ ├── overview.md # Architecture pattern, layers, boundaries
|
||||
│ └── dependency-graph.md # Module dependency graph (no circles!)
|
||||
├── entities/
|
||||
│ └── entities.md # Domain entities, fields, relationships
|
||||
├── db-schema/
|
||||
│ └── schema.md # Tables, columns, indexes, foreign keys
|
||||
├── api-surface/
|
||||
│ └── endpoints.md # API methods, paths, auth, controllers
|
||||
├── conventions/
|
||||
│ └── conventions.md # Naming, patterns, forbidden practices
|
||||
├── maps/
|
||||
│ ├── file-graph.json # Programmatic file→imports/exports graph
|
||||
│ └── module-graph.json # Programmatic module→dependencies graph
|
||||
└── tech-stack/
|
||||
└── stack.md # Languages, frameworks, databases, tools
|
||||
```
|
||||
|
||||
## Orchestrator Integration
|
||||
|
||||
### Docker Execution (REQUIRED)
|
||||
|
||||
**All indexing runs inside a Docker container.** The orchestrator must NEVER run `npm`, `npx`, `bun`, or `node` on the host. All agent tooling is containerized.
|
||||
|
||||
```bash
|
||||
# Build image
|
||||
docker compose -f docker/docker-compose.architect.yml build
|
||||
|
||||
# Run full index
|
||||
docker compose -f docker/docker-compose.architect.yml run --rm architect-indexer
|
||||
|
||||
# Run incremental
|
||||
docker compose -f docker/docker-compose.architect.yml run --rm architect-indexer --mode incremental
|
||||
|
||||
# NPM shortcuts (host → Docker)
|
||||
npm run arch:build
|
||||
npm run arch:index
|
||||
npm run arch:index:full
|
||||
npm run arch:index:incremental
|
||||
```
|
||||
|
||||
### First Contact Check
|
||||
|
||||
```typescript
|
||||
// In orchestrator's first-contact logic:
|
||||
const stateFile = readFileSync('.architect/state.json')
|
||||
const state = JSON.parse(stateFile)
|
||||
|
||||
if (state.status === 'not_indexed' || isStale(state)) {
|
||||
// Launch architect-indexer before any task
|
||||
delegate('architect-indexer', { mode: 'full' })
|
||||
} else if (hasStaleSections(state)) {
|
||||
// Launch incremental update
|
||||
delegate('architect-indexer', { mode: 'incremental', sections: staleSections })
|
||||
}
|
||||
```
|
||||
|
||||
### Staleness Detection
|
||||
|
||||
```typescript
|
||||
function isStale(state: ArchitectState): boolean {
|
||||
const lastUpdate = new Date(state.last_full_index)
|
||||
const hoursSince = (Date.now() - lastUpdate.getTime()) / (1000 * 60 * 60)
|
||||
return hoursSince > state.staleness_threshold_hours
|
||||
}
|
||||
|
||||
function hasStaleSections(state: ArchitectState): string[] {
|
||||
return Object.entries(state.sections)
|
||||
.filter(([_, s]) => s.status === 'stale')
|
||||
.map(([name]) => name)
|
||||
}
|
||||
```
|
||||
|
||||
### After Task Completion
|
||||
|
||||
When `lead-developer` or `the-fixer` complete tasks that modify project structure:
|
||||
1. Check if any new files were created or deleted
|
||||
2. If yes → mark affected sections as `stale` in `state.json`
|
||||
3. On next orchestrator cycle → run incremental update
|
||||
|
||||
## Staleness Rules
|
||||
|
||||
| Event | Sections to Mark Stale |
|
||||
|-------|----------------------|
|
||||
| New/removed file | `file_graph`, `module_graph` |
|
||||
| New dependency | `tech_stack`, full reindex |
|
||||
| New migration | `db_schema` |
|
||||
| New model/entity | `entities` |
|
||||
| New API endpoint | `api_surface` |
|
||||
| Convention change | `conventions` |
|
||||
| Structural refactor | `architecture_overview`, `dependency_graph` |
|
||||
|
||||
## Reading `.architect/` Data
|
||||
|
||||
Agents should read the relevant section before starting work:
|
||||
|
||||
```typescript
|
||||
// Example: Before creating a new model
|
||||
const entities = readFileSync('.architect/entities/entities.md')
|
||||
// Check existing entities, relations, naming conventions
|
||||
|
||||
// Example: Before adding an API endpoint
|
||||
const endpoints = readFileSync('.architect/api-surface/endpoints.md')
|
||||
// Check existing routes, avoid duplicates, follow patterns
|
||||
|
||||
// Example: Before modifying DB schema
|
||||
const schema = readFileSync('.architect/db-schema/schema.md')
|
||||
// Check existing tables, foreign keys, avoid breaking changes
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
1. **Orchestrator**: Check `.architect/state.json` before routing tasks
|
||||
2. **system-analyst**: Read architecture files when designing specs
|
||||
3. **lead-developer**: Read conventions and entity files before coding
|
||||
4. **sdet-engineer**: Read API surface and entity files before writing tests
|
||||
5. **code-skeptic**: Read conventions when reviewing code
|
||||
6. **history-miner**: Compare current vs. indexed state to find changes
|
||||
|
||||
## Schemas
|
||||
|
||||
### project.json Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"indexed_at": "ISO8601",
|
||||
"project": {
|
||||
"name": "string",
|
||||
"type": "laravel|nextjs|express|go-api|flutter|django|fastapi|generic",
|
||||
"framework": "string",
|
||||
"language": "string",
|
||||
"description": "string",
|
||||
"repository": "string",
|
||||
"entry_points": ["string"],
|
||||
"rootDir": "string"
|
||||
},
|
||||
"structure": { "directories": {}, "key_files": {} },
|
||||
"tech_stack": { "languages": [], "frameworks": [], "databases": [], "runtimes": [], "package_managers": [], "testing_frameworks": [], "ci_cd": [] },
|
||||
"modules": [{ "name": "", "path": "", "exports": [], "imports": [] }],
|
||||
"entities": [{ "name": "", "module": "", "fields": [], "relations": [] }],
|
||||
"api_endpoints": [{ "method": "", "path": "", "controller": "", "auth": "" }],
|
||||
"db_tables": [{ "name": "", "columns": [], "indexes": [], "foreign_keys": [] }],
|
||||
"conventions": { "naming": {}, "patterns": [], "forbidden": [] }
|
||||
}
|
||||
```
|
||||
|
||||
### state.json Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"status": "not_indexed|indexed|error",
|
||||
"last_full_index": "ISO8601|null",
|
||||
"last_incremental_update": "ISO8601|null",
|
||||
"last_file_count": 0,
|
||||
"file_hashes": { "path": "sha256hash" },
|
||||
"directory_hashes": { "path": "sha256hash" },
|
||||
"dependency_hashes": { "package_json": "sha256|null" },
|
||||
"sections": {
|
||||
"architecture_overview": { "last_updated": "ISO8601|null", "file_hash": "sha256|null", "status": "stale|fresh|error|missing" },
|
||||
"dependency_graph": { ... },
|
||||
"entities": { ... },
|
||||
"db_schema": { ... },
|
||||
"api_surface": { ... },
|
||||
"conventions": { ... },
|
||||
"tech_stack": { ... },
|
||||
"file_graph": { ... },
|
||||
"module_graph": { ... }
|
||||
},
|
||||
"staleness_threshold_hours": 24
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always check state.json** before reading `.architect/` — if stale, trigger reindex
|
||||
2. **Never manually edit** `.architect/` files — they are auto-generated
|
||||
3. **Commit `.architect/` to git** (except `maps/` which can be large) so team has same orientation
|
||||
4. **Add `.architect/maps/` to `.gitignore`** if file-graph becomes too large
|
||||
5. **After significant changes**, run `/index-project` to force refresh
|
||||
Reference in New Issue
Block a user