Files

tegwick 1c0c0efc56 Reorganize documentation into canonical repository layout

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.

2026-06-08 13:55:27 +02:00

2.1 KiB

Raw Permalink Blame History

AGENTS.md

Guidance for agents working in shard-wiki.

Read First

INTENT.md — aspiration and boundaries (stable; architectural changes are rare).
SCOPE.md — what we are achieving now and current maturity.
.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

pip install -e ".[dev]"
pytest
ruff check
ruff format

State Hub

Workplans register with State Hub. After workplan changes:

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/

2.1 KiB Raw Permalink Blame History Unescape Escape