generated from coulomb/repo-seed
tegwick
1c0c0efc56
Adopt CoulombSocial/HelixForge/MarkiTect documentation structure: - research/260608-yawex-prior-art/ — yawex exploration and sources - demand/ — inbound NetKingdom integration requirements - spec/ — PRD, TSD, UseCaseCatalog, ArchitectureBlueprint scaffolds - docs/ — stakeholder documentation and repository-layout guide - wiki/, issues/, history/ — scaffolded directories Add SCOPE.md and AGENTS.md. Update workplan paths and README.
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/` |