tegwick
f7ad73d9da
Register the InfoTechCanon Repository Layout Standard as a domain standard (itc-repo-layout), processed from demand through the canon's Purpose/Demand intake without collapsing existing model concepts. - Register standard in artifacts/index.yaml, canon.yaml, infospace.yaml; regenerate indexes, views, briefs, tree, and validation (validate green). - T04: add reconciliation.yaml (partial/as-is dogfooding, declared core conformance, recorded tensions); resolve the demand by moving it out of demand/ to the evaluation pack as source-demand.md and removing demand/. - T05: add consumer-adoption-brief.md for downstream repos. - Update test artifact/standard counts (60->61, standards 2->3). - Mark T03/T04/T05 done; workplan and registry status -> finished. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
3.1 KiB
This is a canonical layout for repository contained documentation information. There are various perspectives on why to document what how. This guide provides a system to allow for efficient retrieval of information. The structure is based in best practices from the CoulombSocial, HelixForge, MarkiTect experiences and will evolve over time.
This is a recommendation not a strict requirement. Please base the layout of repositories on the following outline:
INTENT.md captures the aspiration and boundries. We will be working to explore the problemspace and implement a solution and capture a top level view of what we achieve in a SCOPE.md file. Our mode of operation will be closing the gap of SCOPE to INTENT while learning and refining both where necessary. There should be a canonical set of directories for documentation structuring our mode of work as follows.
research/ is a directory to provide results about explorations in the problem and solution space. Each exploration should have a yymmdd-prefix to the markdown file or subdirectory if multiple files or sources are provided. The yawex prior art stuff should go there.
demand/ is a inbound directory for feature requests, requirements, suggestions and opportunities to improve. This directory should contain what has not been systematically reviewed and captured in tasks or workplans. Information here can be raw and needs additional scrutiny to decide if the implementation should pick up on the demand and how.
spec/ is a directory for specification files that provide guidance and guardrails for the implementation. Typically we will establish a ProductRequirementsDocument.md and TechnicalSpecificationDocument.md and maybe UseCaseCatalog.md and ArchitectureBlueprint.md files. Background information on those types of documents can be found in the InfoTechPrimers space on coulomb.social.
workplans/ is a directory for all workplan.md that contain tasks for implementation. Those will be registered with the statehub and should conform to the standards provided by the statehub infrastructure. Workplans that have been finished or canceled should move to history
docs/ is a directory for documentation targeted at stakeholders for the repo be it users, developers, humand or agents. If documentation is wrong or stale it can and should be rewritten based on what the repo actually does.
wiki/ is a directory for interconnected collective gathering of information without a specific perspective. This directory is powerful if connected with an wiki ui where creators, users and investors can collaborate.
issues/ all or some of this information might be captured systematically as tickes in a ticket system. This directory can provide a mirror of relevant open tickets to ease access to the information from customer support, dev-sec-ops work organization tickets and the like.
history/ is a directory to move material to that is no longer needed but should be kept around. Use yymmdd-prefix to mark when some file or directory has been archived. Stuff in history should only be considered if some research or diagnostic needs it. Files here are out of scope for regular daily tasks to not boggle down working memory unnecessarily.