Files

¨NW¨ 6b71ea2b57 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

2026-04-22 20:01:38 +01:00

3.5 KiB

Raw Blame History

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

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.

3.5 KiB Raw Blame History