62 lines
2.1 KiB
Markdown
62 lines
2.1 KiB
Markdown
|
# AGENTS.md
|
|||
|
|
|
|||
|
|
Guidance for agents working in `shard-wiki`.
|
|||
|
|
|
|||
|
|
## Read First
|
|||
|
|
|
|||
|
|
1. `INTENT.md` — aspiration and boundaries (stable; architectural changes are rare).
|
|||
|
|
2. `SCOPE.md` — what we are achieving now and current maturity.
|
|||
|
|
3. `.custodian-brief.md` — State Hub snapshot (generated; do not edit manually).
|
|||
|
|
|
|||
|
|
## Documentation Layout
|
|||
|
|
|
|||
|
|
This repo follows the CoulombSocial / HelixForge / MarkiTect documentation
|
|||
|
|
layout (recommendation, not strict law). Efficient retrieval by purpose:
|
|||
|
|
|
|||
|
|
| Path | Purpose |
|
|||
|
|
|------|---------|
|
|||
|
|
| `INTENT.md` | Aspiration and boundaries |
|
|||
|
|
| `SCOPE.md` | Top-level view of current achievement; closes gap to INTENT |
|
|||
|
|
| `research/` | Exploration results (`yymmdd-` prefix on files or subdirs) |
|
|||
|
|
| `demand/` | Inbound requests not yet reviewed into spec or workplans |
|
|||
|
|
| `spec/` | Implementation guardrails (PRD, TSD, use cases, architecture) |
|
|||
|
|
| `workplans/` | State Hub–registered implementation tasks |
|
|||
|
|
| `docs/` | Stakeholder documentation (users, developers, humans, agents) |
|
|||
|
|
| `wiki/` | Perspective-free interconnected knowledge (wiki UI when connected) |
|
|||
|
|
| `issues/` | Mirror of relevant open tickets when ticket systems are in use |
|
|||
|
|
| `history/` | Archived material (`yymmdd-` prefix); out of scope for daily work |
|
|||
|
|
|
|||
|
|
**Mode of operation:** close SCOPE → INTENT while learning; refine both as needed.
|
|||
|
|
|
|||
|
|
## Domain Vocabulary
|
|||
|
|
|
|||
|
|
Honor terms from `INTENT.md`: shard, root entity, adapter contract, projection,
|
|||
|
|
overlay, coordination journal, shard modes. Do not invent parallel vocabulary.
|
|||
|
|
|
|||
|
|
## Build And Test
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pip install -e ".[dev]"
|
|||
|
|
pytest
|
|||
|
|
ruff check
|
|||
|
|
ruff format
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## State Hub
|
|||
|
|
|
|||
|
|
Workplans register with State Hub. After workplan changes:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd ~/state-hub && make fix-consistency REPO=shard-wiki
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Finished or canceled workplans move to `history/` with a `yymmdd-` archive prefix.
|
|||
|
|
|
|||
|
|
## Where To Put New Material
|
|||
|
|
|
|||
|
|
- Exploratory analysis → `research/yymmdd-<topic>/`
|
|||
|
|
- Raw feature ask or external requirement → `demand/`
|
|||
|
|
- Reviewed design ready to guide code → `spec/`
|
|||
|
|
- Implementation tasks → `workplans/`
|
|||
|
|
- User/dev/agent how-to → `docs/`
|
|||
|
|
- Collaborative unstructured notes → `wiki/`
|