project-conventions

Name: project-conventions
Author: pssah4

34stars5forks

How to install project-conventions?

pssah4/digital-innovation-agents/project-conventions

$npx -y skills add pssah4/digital-innovation-agents --skill project-conventions

Installs into the current project.

Summary

Defines project structure, naming conventions, and way of working for all projects. Referenced by other skills to ensure consistent directory structures, file names, and documentation standards. Use this skill when the user mentions "project setup", "project structure", "conventi

Files · 1

View on GitHub

SKILL.md

1	# Project Structure & Conventions
2
3	This skill defines the binding standards for directory structures, file
4	names, and ways of working. All other skills (BA, RE, Architecture, Coding,
5	Testing, Security Audit) follow these conventions.
6
7	## Codebase-Awareness -- Core Principle
8
9	All skills operate in the context of the existing codebase, never in a
10	vacuum. Read `references/codebase-awareness.md` for the complete rules.
11
12	Summary: Before any work, read existing code, recognize patterns, understand
13	dependencies, check reference implementations. The project's `CLAUDE.md`
14	takes PRECEDENCE over generic skill instructions.
15
16	## Canonical Specs (single home; other skills link here)
17
18	These specs are the canonical source for every V-Model skill (BA, RE,
19	Architecture, Coding, Testing, Security-Audit, Consistency-Check,
20	Reverse-Engineering). Phase skills do not restate them; they link
21	back to this section. Templates do not pre-render them; they leave
22	placeholders that the producing skill fills based on the rules here.
23
24	### 1. Reader budget (the under-2-minute rule)
25
26	Every produced artifact must be scannable by a human reader in under
27	two minutes. The number that operationalizes this is a per-artifact
28	hard line cap. Skills measure with `wc -l` against the cap before
29	handoff.
30
31	Exceeding the cap. A cap may be exceeded only with a one-line
32	justification at the top of the file:
33
34	```markdown
35	## Reasoned exception
36
37	Cap raised from <N> to <M> lines: <one-sentence reason>.
38	```
39
40	Without that block, `/consistency-check` flags the artifact as
41	over-cap. The exception block is read during review; agents do not
42	add it routinely.
43
44	Hard caps (binding).
45
46	\| Artifact \| Cap \| Notes \|
47	\|---\|---\|---\|
48	\| Project-BA \| 200 lines \| Initial discovery only \|
49	\| EPIC-BA \| 120 lines \| Item-BA at epic scope \|
50	\| FEAT-BA \| 60 lines \| Item-BA at feature scope \|
51	\| BA-MINI (IMP/FIX) \| 40 lines \| \|
52	\| EXPLORATION-BOARD \| 70 lines \| Scratchpad \|
53	\| EPIC \| 40 lines \| \|
54	\| FEATURE \| 65 lines \| \|
55	\| BACKLOG \| 80 lines + rows \| Header+vocab leg+pointers cap; rows uncapped \|
56	\| ARCHITECT-HANDOFF \| 60 lines \| Dialog grows in-place \|
57	\| ADR \| 60 lines \| Excluding optional Implementation Notes; includes 7-line German-variant translation note \|
58	\| arc42 \| 65 lines (PoC) / 100 (MVP) \| \|
59	\| plan-context \| 55 lines \| \|
60	\| PLAN \| 50 lines \| Plus uncapped Change Log tail \|
61	\| FIX \| 32 lines \| \|
62	\| IMP \| 30 lines \| \|
63	\| AUDIT \| 65 lines \| Plus uncapped finding tables \|
64	\| METRICS \| 50 lines \| \|
65	\| ARCHITECTURE-MAP, MODULE-README, JSDOC-HEADER, RULES-* \| per-template caps in template comments \| \|
66
67	### 2. Frontmatter spec
68
69	Artifact frontmatter carries identity and relations only. No state.
70
71	Allowed keys.
72
73	- Identity: `id`, `title`, `date` (creation date)
74	- Relations (only present when populated):
75	- `epic`: parent epic id (string), used by FEAT/IMP/FIX/PLAN
76	- `feature`: parent feature id (string), used by IMP/FIX/PLAN
77	- `ba-ref`: relative path to the Item-BA (string), used by EPIC/FEAT/IMP/FIX
78	- `project-ba-ref`: relative path to `BA-{PROJECT}.md` (string), MANDATORY on every Item-BA
79	- `hmw-ref`: link to the HMW question this artifact answers (string, optional)
80	- `adr-refs`: list of ADR ids (used by FEAT/PLAN)
81	- `feature-refs`: list of FEAT ids (used by ADR)
82	- `supersedes`, `superseded-by`: ADR linkage (strings)
83	- `subtype`: `user-facing` or `library` (FEATURE only)
84	- `depends-on`: list of artifact ids (cross-cutting dependency)
85
86	Forbidden keys. `status`, `phase`, `last_updated`, `last-updated`,
87	`lastUpdated`, `author`, `owner`, `claim`. State lives in the BACKLOG
88	row. Frontmatter status is stripped by
89	`tools/migration/strip_frontmatter_status.py` and flagged as N-15
90	by `/consistency-check`.
91
92	Empty refs are omitted, never stubbed as `[]`. If a feature has no
93	ADRs, omit `adr-refs`; do not write `adr-refs: []`. Stub keys add
94	noise and trigger false-positive graph edges.
95
96	### 3. Backlog vocabulary
97
98	The BACKLOG.md table column order is binding (parsed by index in
99	four tools): `\| ID \| Type \| Title \| Status \| Phase \| Prio \| Refs \| Source \| Commit \| Claim \| Last change \| Notes \|`.
100
101	Status (artifact lifecycle). Aligned 1:1 with GitHub Projects so
102	`flow.py sync-status` stays consistent.
103
104	- `Backlog`: captured, not yet prioritized. Also the resting place for
105	blocked or deferred items.
106	- `Ready`: prioritized, scheduled, free to be claimed.
107	- `In Progress`: someone is actively working on it.
108	- `In Review`: PR open, awaiting review or quality gates.
109	- `Done`: merged. Row

People who liked this also viewed

6 picks

Type

project-conventions

34stars5forks

View on GitHub

How to install project-conventions?

pssah4/digital-innovation-agents/project-conventions

$npx -y skills add pssah4/digital-innovation-agents --skill project-conventions

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Project Structure & Conventions
2
3	This skill defines the binding standards for directory structures, file
4	names, and ways of working. All other skills (BA, RE, Architecture, Coding,
5	Testing, Security Audit) follow these conventions.
6
7	## Codebase-Awareness -- Core Principle
8
9	All skills operate in the context of the existing codebase, never in a
10	vacuum. Read `references/codebase-awareness.md` for the complete rules.
11
12	Summary: Before any work, read existing code, recognize patterns, understand
13	dependencies, check reference implementations. The project's `CLAUDE.md`
14	takes PRECEDENCE over generic skill instructions.
15
16	## Canonical Specs (single home; other skills link here)
17
18	These specs are the canonical source for every V-Model skill (BA, RE,
19	Architecture, Coding, Testing, Security-Audit, Consistency-Check,
20	Reverse-Engineering). Phase skills do not restate them; they link
21	back to this section. Templates do not pre-render them; they leave
22	placeholders that the producing skill fills based on the rules here.
23
24	### 1. Reader budget (the under-2-minute rule)
25
26	Every produced artifact must be scannable by a human reader in under
27	two minutes. The number that operationalizes this is a per-artifact
28	hard line cap. Skills measure with `wc -l` against the cap before
29	handoff.
30
31	Exceeding the cap. A cap may be exceeded only with a one-line
32	justification at the top of the file:
33
34	```markdown
35	## Reasoned exception
36
37	Cap raised from <N> to <M> lines: <one-sentence reason>.
38	```
39
40	Without that block, `/consistency-check` flags the artifact as
41	over-cap. The exception block is read during review; agents do not
42	add it routinely.
43
44	Hard caps (binding).
45
46	\| Artifact \| Cap \| Notes \|
47	\|---\|---\|---\|
48	\| Project-BA \| 200 lines \| Initial discovery only \|
49	\| EPIC-BA \| 120 lines \| Item-BA at epic scope \|
50	\| FEAT-BA \| 60 lines \| Item-BA at feature scope \|
51	\| BA-MINI (IMP/FIX) \| 40 lines \| \|
52	\| EXPLORATION-BOARD \| 70 lines \| Scratchpad \|
53	\| EPIC \| 40 lines \| \|
54	\| FEATURE \| 65 lines \| \|
55	\| BACKLOG \| 80 lines + rows \| Header+vocab leg+pointers cap; rows uncapped \|
56	\| ARCHITECT-HANDOFF \| 60 lines \| Dialog grows in-place \|
57	\| ADR \| 60 lines \| Excluding optional Implementation Notes; includes 7-line German-variant translation note \|
58	\| arc42 \| 65 lines (PoC) / 100 (MVP) \| \|
59	\| plan-context \| 55 lines \| \|
60	\| PLAN \| 50 lines \| Plus uncapped Change Log tail \|
61	\| FIX \| 32 lines \| \|
62	\| IMP \| 30 lines \| \|
63	\| AUDIT \| 65 lines \| Plus uncapped finding tables \|
64	\| METRICS \| 50 lines \| \|
65	\| ARCHITECTURE-MAP, MODULE-README, JSDOC-HEADER, RULES-* \| per-template caps in template comments \| \|
66
67	### 2. Frontmatter spec
68
69	Artifact frontmatter carries identity and relations only. No state.
70
71	Allowed keys.
72
73	- Identity: `id`, `title`, `date` (creation date)
74	- Relations (only present when populated):
75	- `epic`: parent epic id (string), used by FEAT/IMP/FIX/PLAN
76	- `feature`: parent feature id (string), used by IMP/FIX/PLAN
77	- `ba-ref`: relative path to the Item-BA (string), used by EPIC/FEAT/IMP/FIX
78	- `project-ba-ref`: relative path to `BA-{PROJECT}.md` (string), MANDATORY on every Item-BA
79	- `hmw-ref`: link to the HMW question this artifact answers (string, optional)
80	- `adr-refs`: list of ADR ids (used by FEAT/PLAN)
81	- `feature-refs`: list of FEAT ids (used by ADR)
82	- `supersedes`, `superseded-by`: ADR linkage (strings)
83	- `subtype`: `user-facing` or `library` (FEATURE only)
84	- `depends-on`: list of artifact ids (cross-cutting dependency)
85
86	Forbidden keys. `status`, `phase`, `last_updated`, `last-updated`,
87	`lastUpdated`, `author`, `owner`, `claim`. State lives in the BACKLOG
88	row. Frontmatter status is stripped by
89	`tools/migration/strip_frontmatter_status.py` and flagged as N-15
90	by `/consistency-check`.
91
92	Empty refs are omitted, never stubbed as `[]`. If a feature has no
93	ADRs, omit `adr-refs`; do not write `adr-refs: []`. Stub keys add
94	noise and trigger false-positive graph edges.
95
96	### 3. Backlog vocabulary
97
98	The BACKLOG.md table column order is binding (parsed by index in
99	four tools): `\| ID \| Type \| Title \| Status \| Phase \| Prio \| Refs \| Source \| Commit \| Claim \| Last change \| Notes \|`.
100
101	Status (artifact lifecycle). Aligned 1:1 with GitHub Projects so
102	`flow.py sync-status` stays consistent.
103
104	- `Backlog`: captured, not yet prioritized. Also the resting place for
105	blocked or deferred items.
106	- `Ready`: prioritized, scheduled, free to be claimed.
107	- `In Progress`: someone is actively working on it.
108	- `In Review`: PR open, awaiting review or quality gates.
109	- `Done`: merged. Row

People who liked this also viewed

6 picks

Type