Skip to content

Commit 4509731

Browse files
ivklgnivklgn
committed
feat: add spec, make more balanced doc, remove unused project type
1 parent f12a46d commit 4509731

13 files changed

Lines changed: 774 additions & 108 deletions

‎.archcore/.sync-state.json‎

Lines changed: 105 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,53 @@
11
{
22
"version": 1,
33
"files": {
4-
"cli-ui/building-the-cli.guide.md": "ab1466d9ee5d17ae9d73ca545cc8ca6b1d7dd11864034ff964676de88afde64d",
4+
"cli-ui/building-the-cli.guide.md": "b9af193c4702f7cd58ef397626bed6883128171a1ef8f08b8f939aab271bc194",
5+
"cli-ui/language-setting.idea.md": "15f4825bc8f52cea1f249e6cc601997a62357584756f99affcd45642cda2e07d",
56
"cli-ui/project-deletion-via-repo.idea.md": "88984fdff4a5e8af797a4d4322ed6e4c17e81c541c9a35959f2db29a2a9055cb",
6-
"dir/archcore-directory-structure.guide.md": "39972d4391ce460a25d7560a85b9e0f706d9d3e356626ba855db3887c45992cb",
7-
"dir/free-form-directory-rules.rule.md": "f9db0f527900e33f49cd5ae3bc0db71e1c30b0cbbda87baa3f3922e55be56f17",
8-
"dir/free-form-directory-structure.adr.md": "ab2fbd9114a6695ae197b56fcaf7a91ea93407c6aec2dcf603285b634e34ab71",
7+
"cli-ui/version-in-banners.idea.md": "af87637c17ae6daab662b1be2166fafd4650ff861d91f4e281ca0019381f46ca",
8+
"cli/archcore-first-search-priority.rule.md": "9a8bf693cbd1d8122cef2f9da7ae93930ea67388aa859848170e788628a3816a",
9+
"cli/feature-gating-at-command-layer.rule.md": "6f1455376768506f232ec5b17002b3bae6565f8e1f5d0eca50880b7efa2456d2",
10+
"cli/import-existing-context.idea.md": "5818488f4ff837b7d5f5e23124938f403d9f0b8345ca5caed6860831369a8356",
11+
"cli/optional-settings-omit-defaults.rule.md": "9ea14bac983c2ed489114261a761b8da0760c668216fa988899b466e0170a471",
12+
"dir/archcore-directory-structure.guide.md": "0bcd20721e9b69e05e9a31f5b1da2d38254707e0f593c7609a860094c4f4b0a1",
13+
"dir/categories-and-document-types.doc.md": "9ae300c1a074fa5980a174f71fcbef1bcd449317d0317d8f59a42037a3d0ee59",
14+
"dir/free-form-directory-rules.rule.md": "3122fbd4a096662d1e6b84aa2cd5f8c234364db9eef43eeff8cd78e8b9be2a84",
15+
"dir/free-form-directory-structure.adr.md": "359025839a37daeffe59dab3a19a599afffa6229da73edca3e4e47b5e90a4ab7",
16+
"document-types/iso-29148-document-types-implementation.plan.md": "163d65b856a0df5616c89565e28b4758bb70fe877f15a5687075d032e577e79b",
17+
"document-types/mrd-brd-urd-implementation.plan.md": "d97a1fe1c5c1aa53406b07177bea67acb7c35a03dad0f1bc7b3a83d2f01a89b3",
18+
"document-types/mrd-brd-urd-requirement-sources.idea.md": "56d584fe86b34c22a5476beb6219df39509e789c3055e32986fe105f60c83373",
19+
"document-types/prd-vs-iso-29148-requirements-strategy.idea.md": "ed4ad8c51809a32cb29687553578ae651d4fe1789a39aa1d9dcf7b12f7a32972",
20+
"document-types/remove-project-document-type.adr.md": "2d70783d975b6b31b034903455fb952f32ca727443155bce98d929154593c333",
21+
"document-types/spec-type-usage.rule.md": "051098a115e5e557213cd5d2b5fa9e460e32b205c8ab5771156679de14fe0fbd",
22+
"document-types/writing-spec-documents.guide.md": "af5f8272bf40ae719673fea86492c0be76e3ed5e7e286121aff9336e07f35a1b",
923
"integrations/agent-hooks-integration.guide.md": "54509050bc6accbbcb0170c8f2c4df56c3708da8959b58ff6ac24de0dd8dbc52",
1024
"integrations/backup-invalid-configs.adr.md": "a96a5ad0cc21737560940e073c6ae4d62dd22ec82db3a87bee19bbf55ac9567a",
11-
"integrations/cli-hooks-reference.doc.md": "54d8340e368ff89b38f859be6323c75d818f329fe36b653c2bd2818af3e2910e",
12-
"integrations/supported-ai-agents.doc.md": "151308f93087835af5a026297b2a1fb2bee8cf9808b095e83965a5b34f1dbca6",
25+
"integrations/cli-hooks-reference.doc.md": "38877e79d349529fd654d1000190e324c2676e62fa2f73e51a2b2bf503fe36e2",
26+
"integrations/disable-stop-and-prompt-hooks.adr.md": "420b04465a7e59de2d2368887ff71c1e2f41e86ac419b890834c154551b6e744",
27+
"integrations/supported-ai-agents.doc.md": "72b776f3398551d157f1b15a10386dd17045c7d213f3939f9a6160b87e4ccaab",
28+
"mcp/no-absolute-paths-in-mcp-errors.rule.md": "0fc86b170ce9d775901c8396bf6ccec3481b54d12e364bf87f73cb3b8400a376",
29+
"mcp/tags-implementation.plan.md": "fdfa04b70f085bc5b0cf873546d5d44730b595f0961541bd1014b368f630bb61",
30+
"relations/local-relations-in-sync-state.adr.md": "8b7cf80c829465156ad27040f6365c7f91e5e9ceddb112242a88f533840bebf0",
31+
"release/how-to-release.guide.md": "d43f8e096454e9a6408dbaa02282272411389823a3654d4e5648a2efb1f57422",
32+
"release/install-script-usage.guide.md": "54034c7cf400d7940620b9fc579a8187aa48d0e4f330edd91dde3fff91c803e9",
33+
"release/release-infrastructure.doc.md": "7a3bf8de0faf6296a2fbd83be4381c19698ca40664853934b061a0f219d3ce53",
34+
"release/version-injection-via-ldflags.rule.md": "5e46bfc5238f58906a1b4bf2d1aa17743d37df667c841340bf6e4d7703e6c871",
35+
"sync/auto-detect-repo-url-on-sync.adr.md": "2ed41cd122176c9f6461fb90ca005b2a75d2b8cd9e66de364b386a38c47c689b",
1336
"sync/one-way-push-sync-strategy.adr.md": "911131db9ba1bf575ab9d3f091138d07b27bca2fbcddd411ca2f8c2a881a57c5",
14-
"sync/sync-command-implementation.plan.md": "9f35747efe19d7d39f7561c0e2f9ad2300c8bc0fedbab4fb21d58dc31164c072",
15-
"sync/sync-design.idea.md": "fdba2863c7fed87a6ca87750ef1d36f78130802dc4fba70b18e22b943c375a3f",
16-
"sync/sync-how-it-works.guide.md": "393a152643c6de561f3f7f9bc594b669b0c84766ecbae269d9d61fd7cbd15d96",
37+
"sync/sync-command-implementation.plan.md": "40dba775242834c898681f47c0c0eca6fe9b141f0a081f4252f477413142db6a",
38+
"sync/sync-design.idea.md": "8fa7b2125e7a92ffb1220d1dcafd2512e61666b1f621fce56950c66cc9e59da0",
39+
"sync/sync-how-it-works.guide.md": "541b1285ce3f3428f09c897c96de0ce88cfaef9b2ad462ff79de9376f300f409",
1740
"sync/sync-manifest-update-on-success-only.rule.md": "49dc9ff0f029dc1436d15a8ff60d56d19c830ce2df5c5ed3357221db9472373f",
18-
"sync/sync-mode-field-validation.rule.md": "766604fee1572f7a2f24a1c1ed917009eff8909f21aebeceff38eca948547ba7",
41+
"sync/sync-mode-field-validation.rule.md": "978a5da40a0a187e3fa8b8899f4666ebbd6f9e8ed78afc28c3fb1c620d1bbfba",
1942
"sync/sync-path-security.rule.md": "256768e99f55331cd857ffa3056668f2a5a5f9be7f5a998bca59137a93265937",
20-
"sync/sync-source-of-truth.rule.md": "c36526edd5d7e9bcd8b692227a3dfa3810fe46b49d9c35b67497574e22bf14b3"
43+
"sync/sync-source-of-truth.rule.md": "c36526edd5d7e9bcd8b692227a3dfa3810fe46b49d9c35b67497574e22bf14b3",
44+
"sync/temporarily-disable-sync.adr.md": "e0df05e12a2654e37c98654ca3abb84dc85ee5110de658cc3c0bac168d909524",
45+
"telemetry/telemetry-provider-selection.rfc.md": "fcadaa62249c6dcc437e71852bb8c598a9dc412c5eb9ede68871a080ecddc153",
46+
"update/self-update-command.guide.md": "e14595e532bfc750b99598887e4bb7ef4ea74a20942f9192f820db0f5b20c5a2",
47+
"update/update-version-check-strategy.rfc.md": "6680f6bfc9e561c997ba17a9b436e54ff71c920a22cdad3d2eb1f9254c9bba1c",
48+
"update/version-check-proxy.idea.md": "7bec4bfb32dac8330d4521a3648404e767e09d58bfaf55c250b02fd98f2a33b8"
2149
},
2250
"relations": [
23-
{
24-
"source": "cli-ui/language-setting-no-mcp-effect.cpat.md",
25-
"target": "cli-ui/language-setting.idea.md",
26-
"type": "related"
27-
},
2851
{
2952
"source": "cli/optional-settings-omit-defaults.rule.md",
3053
"target": "cli-ui/language-setting.idea.md",
@@ -81,139 +104,149 @@
81104
"type": "related"
82105
},
83106
{
84-
"source": "cli/version-check-proxy.idea.md",
85-
"target": "cli/archcore-first-search-priority.rule.md",
107+
"source": "dir/categories-and-document-types.doc.md",
108+
"target": "dir/archcore-directory-structure.guide.md",
86109
"type": "related"
87110
},
88111
{
89-
"source": "cli/version-check-proxy.idea.md",
90-
"target": "cli/feature-gating-at-command-layer.rule.md",
112+
"source": "dir/categories-and-document-types.doc.md",
113+
"target": "dir/free-form-directory-rules.rule.md",
91114
"type": "related"
92115
},
93116
{
94-
"source": "cli/version-check-proxy.idea.md",
95-
"target": "cli/optional-settings-omit-defaults.rule.md",
117+
"source": "dir/categories-and-document-types.doc.md",
118+
"target": "dir/free-form-directory-structure.adr.md",
96119
"type": "related"
97120
},
98121
{
99-
"source": "cli/update-version-check-strategy.rfc.md",
100-
"target": "cli/archcore-first-search-priority.rule.md",
122+
"source": "document-types/iso-29148-document-types-implementation.plan.md",
123+
"target": "document-types/prd-vs-iso-29148-requirements-strategy.idea.md",
101124
"type": "related"
102125
},
103126
{
104-
"source": "cli/update-version-check-strategy.rfc.md",
105-
"target": "cli/feature-gating-at-command-layer.rule.md",
127+
"source": "document-types/mrd-brd-urd-requirement-sources.idea.md",
128+
"target": "document-types/iso-29148-document-types-implementation.plan.md",
106129
"type": "related"
107130
},
108131
{
109-
"source": "cli/update-version-check-strategy.rfc.md",
110-
"target": "cli/optional-settings-omit-defaults.rule.md",
132+
"source": "document-types/mrd-brd-urd-requirement-sources.idea.md",
133+
"target": "document-types/prd-vs-iso-29148-requirements-strategy.idea.md",
111134
"type": "related"
112135
},
113136
{
114-
"source": "cli/update-version-check-strategy.rfc.md",
115-
"target": "cli/version-check-proxy.idea.md",
137+
"source": "document-types/mrd-brd-urd-implementation.plan.md",
138+
"target": "document-types/iso-29148-document-types-implementation.plan.md",
116139
"type": "related"
117140
},
118141
{
119-
"source": "cli/update-version-check-strategy.rfc.md",
120-
"target": "cli/version-check-proxy.idea.md",
121-
"type": "extends"
142+
"source": "document-types/mrd-brd-urd-implementation.plan.md",
143+
"target": "document-types/prd-vs-iso-29148-requirements-strategy.idea.md",
144+
"type": "related"
145+
},
146+
{
147+
"source": "document-types/mrd-brd-urd-implementation.plan.md",
148+
"target": "document-types/mrd-brd-urd-requirement-sources.idea.md",
149+
"type": "implements"
122150
},
123151
{
124-
"source": "cli/self-update-command.guide.md",
125-
"target": "cli/archcore-first-search-priority.rule.md",
152+
"source": "mcp/tags-implementation.plan.md",
153+
"target": "mcp/no-absolute-paths-in-mcp-errors.rule.md",
126154
"type": "related"
127155
},
128156
{
129-
"source": "cli/self-update-command.guide.md",
130-
"target": "cli/feature-gating-at-command-layer.rule.md",
157+
"source": "mcp/tags-implementation.plan.md",
158+
"target": "dir/free-form-directory-structure.adr.md",
159+
"type": "extends"
160+
},
161+
{
162+
"source": "document-types/spec-type-usage.rule.md",
163+
"target": "document-types/iso-29148-document-types-implementation.plan.md",
131164
"type": "related"
132165
},
133166
{
134-
"source": "cli/self-update-command.guide.md",
135-
"target": "cli/optional-settings-omit-defaults.rule.md",
167+
"source": "document-types/spec-type-usage.rule.md",
168+
"target": "document-types/mrd-brd-urd-implementation.plan.md",
136169
"type": "related"
137170
},
138171
{
139-
"source": "cli/self-update-command.guide.md",
140-
"target": "cli/update-version-check-strategy.rfc.md",
172+
"source": "document-types/spec-type-usage.rule.md",
173+
"target": "document-types/mrd-brd-urd-requirement-sources.idea.md",
141174
"type": "related"
142175
},
143176
{
144-
"source": "cli/self-update-command.guide.md",
145-
"target": "cli/version-check-proxy.idea.md",
177+
"source": "document-types/spec-type-usage.rule.md",
178+
"target": "document-types/prd-vs-iso-29148-requirements-strategy.idea.md",
146179
"type": "related"
147180
},
148181
{
149-
"source": "cli/self-update-command.guide.md",
150-
"target": "release/release-infrastructure.doc.md",
151-
"type": "depends_on"
182+
"source": "document-types/writing-spec-documents.guide.md",
183+
"target": "document-types/iso-29148-document-types-implementation.plan.md",
184+
"type": "related"
152185
},
153186
{
154-
"source": "cli/self-update-command.guide.md",
155-
"target": "release/install-script-usage.guide.md",
187+
"source": "document-types/writing-spec-documents.guide.md",
188+
"target": "document-types/mrd-brd-urd-implementation.plan.md",
156189
"type": "related"
157190
},
158191
{
159-
"source": "telemetry/telemetry-provider-selection.rfc.md",
160-
"target": "telemetry/posthog-telemetry-implementation.plan.md",
192+
"source": "document-types/writing-spec-documents.guide.md",
193+
"target": "document-types/mrd-brd-urd-requirement-sources.idea.md",
161194
"type": "related"
162195
},
163196
{
164-
"source": "dir/categories-and-document-types.doc.md",
165-
"target": "dir/archcore-directory-structure.guide.md",
197+
"source": "document-types/writing-spec-documents.guide.md",
198+
"target": "document-types/prd-vs-iso-29148-requirements-strategy.idea.md",
166199
"type": "related"
167200
},
168201
{
169-
"source": "dir/categories-and-document-types.doc.md",
170-
"target": "dir/free-form-directory-rules.rule.md",
202+
"source": "document-types/writing-spec-documents.guide.md",
203+
"target": "document-types/spec-type-usage.rule.md",
171204
"type": "related"
172205
},
173206
{
174-
"source": "dir/categories-and-document-types.doc.md",
175-
"target": "dir/free-form-directory-structure.adr.md",
207+
"source": "document-types/spec-type-usage.rule.md",
208+
"target": "dir/categories-and-document-types.doc.md",
176209
"type": "related"
177210
},
178211
{
179-
"source": "document-types/iso-29148-document-types-implementation.plan.md",
180-
"target": "document-types/prd-vs-iso-29148-requirements-strategy.idea.md",
212+
"source": "document-types/writing-spec-documents.guide.md",
213+
"target": "dir/categories-and-document-types.doc.md",
181214
"type": "related"
182215
},
183216
{
184-
"source": "document-types/mrd-brd-urd-requirement-sources.idea.md",
217+
"source": "document-types/remove-project-document-type.adr.md",
185218
"target": "document-types/iso-29148-document-types-implementation.plan.md",
186219
"type": "related"
187220
},
188221
{
189-
"source": "document-types/mrd-brd-urd-requirement-sources.idea.md",
190-
"target": "document-types/prd-vs-iso-29148-requirements-strategy.idea.md",
222+
"source": "document-types/remove-project-document-type.adr.md",
223+
"target": "document-types/mrd-brd-urd-implementation.plan.md",
191224
"type": "related"
192225
},
193226
{
194-
"source": "document-types/mrd-brd-urd-implementation.plan.md",
195-
"target": "document-types/iso-29148-document-types-implementation.plan.md",
227+
"source": "document-types/remove-project-document-type.adr.md",
228+
"target": "document-types/mrd-brd-urd-requirement-sources.idea.md",
196229
"type": "related"
197230
},
198231
{
199-
"source": "document-types/mrd-brd-urd-implementation.plan.md",
232+
"source": "document-types/remove-project-document-type.adr.md",
200233
"target": "document-types/prd-vs-iso-29148-requirements-strategy.idea.md",
201234
"type": "related"
202235
},
203236
{
204-
"source": "document-types/mrd-brd-urd-implementation.plan.md",
205-
"target": "document-types/mrd-brd-urd-requirement-sources.idea.md",
206-
"type": "implements"
237+
"source": "document-types/remove-project-document-type.adr.md",
238+
"target": "document-types/spec-type-usage.rule.md",
239+
"type": "related"
207240
},
208241
{
209-
"source": "mcp/tags-implementation.plan.md",
210-
"target": "mcp/no-absolute-paths-in-mcp-errors.rule.md",
242+
"source": "document-types/remove-project-document-type.adr.md",
243+
"target": "document-types/writing-spec-documents.guide.md",
211244
"type": "related"
212245
},
213246
{
214-
"source": "mcp/tags-implementation.plan.md",
215-
"target": "dir/free-form-directory-structure.adr.md",
216-
"type": "extends"
247+
"source": "document-types/remove-project-document-type.adr.md",
248+
"target": "dir/categories-and-document-types.doc.md",
249+
"type": "related"
217250
}
218251
]
219252
}

‎.archcore/cli/import-existing-context.idea.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ An `archcore import` command that takes existing context files (CLAUDE.md, .curs
4545
2. **Parse and map**: split the file into logical blocks, each block → a separate archcore document:
4646
- Build/test instructions → `guide`
4747
- Rules and conventions → `rule`
48-
- Architecture/overview → `project` or `doc`
48+
- Architecture/overview → `doc`
4949
- If meaningful splitting isn't possible → a single `doc` with the imported content
5050

5151
3. **CLI interface**:

‎.archcore/dir/categories-and-document-types.doc.md‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,16 @@ Documents that describe the future: what we want to build and why.
1919

2020
## Knowledge
2121

22-
Documents that capture what we know: decisions, standards, and reference material.
22+
Documents that capture what we know: decisions, standards, contracts, and reference material.
2323

24-
| Type | Purpose |
25-
| --------- | ------------------------------------------------------------------------ |
26-
| `adr` | A technical decision that has been made, with context and alternatives |
27-
| `rfc` | A proposal open for review before a decision is made |
28-
| `rule` | A mandatory standard — imperative statements with good/bad examples |
29-
| `guide` | Step-by-step instructions for completing a task |
30-
| `doc` | General reference — tables, registries, explanations |
31-
| `project` | Project overview with architecture, components, and getting-started info |
24+
| Type | Purpose |
25+
| --------- | ----------------------------------------------------------------------------------------------------------- |
26+
| `adr` | A technical decision that has been made, with context and alternatives |
27+
| `rfc` | A proposal open for review before a decision is made |
28+
| `rule` | A mandatory standard — imperative statements with good/bad examples |
29+
| `guide` | Step-by-step instructions for completing a task |
30+
| `spec` | Canonical normative contract — behavior, constraints, invariants, conformance for a specific technical boundary |
31+
| `doc` | Non-behavioral reference — tables, registries, glossaries, component lists |
3232

3333
## Experience
3434

@@ -41,8 +41,11 @@ Documents that encode proven patterns and lessons from practice.
4141

4242
## Choosing the Right Type
4343

44-
- **rule vs doc** — rule prescribes behavior ("Always do X") with enforcement. doc describes what exists. Descriptive content → doc.
44+
- **rule vs doc** — rule prescribes behavior ("Always do X") with enforcement. doc describes what exists (tables, registries). Descriptive, non-behavioral content → doc.
4545
- **adr vs rfc** — adr = decision already final. rfc = proposal open for feedback.
4646
- **guide vs doc** — guide has sequential steps to follow. doc is non-sequential reference to look up.
47+
- **spec vs doc** — spec defines a canonical normative contract for a concrete technical boundary (behavior, constraints, invariants, conformance). doc describes what exists without normative requirements. Normative contract → spec; structural reference → doc.
48+
- **spec vs rule** — spec is a technical contract for one component. rule is a cross-cutting team standard. Scoped to a named artifact → spec; applied team-wide → rule.
49+
- **spec vs adr** — spec is the living canonical truth (present-tense: "it works this way"). adr is the decision record (past-tense: "we chose this because"). Both may exist for the same component.
4750
- **task-type vs guide** — task-type is a reusable pattern for a class of tasks (e.g., "how to create a UI-kit component"). guide is instructions for a specific one-time procedure.
4851
- **cpat vs adr** — cpat focuses on a code pattern change with before/after examples. adr records a broader architectural decision with alternatives and consequences.

0 commit comments

Comments
 (0)