@ncoderz/awa 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/README.md +96 -16
  2. package/dist/chunk-3SSUJFKN.js +625 -0
  3. package/dist/chunk-3SSUJFKN.js.map +1 -0
  4. package/dist/config-2TOQATI3.js +10 -0
  5. package/dist/config-2TOQATI3.js.map +1 -0
  6. package/dist/index.js +2190 -414
  7. package/dist/index.js.map +1 -1
  8. package/package.json +10 -4
  9. package/templates/awa/.agent/skills/awa-align/SKILL.md +3 -0
  10. package/templates/awa/.agent/skills/awa-check/SKILL.md +4 -0
  11. package/templates/awa/.agent/skills/awa-usage/SKILL.md +3 -0
  12. package/templates/awa/.agent/workflows/awa-align.md +3 -0
  13. package/templates/awa/.agent/workflows/awa-check.md +4 -0
  14. package/templates/awa/.agents/skills/awa-align/SKILL.md +3 -0
  15. package/templates/awa/.agents/skills/awa-check/SKILL.md +4 -0
  16. package/templates/awa/.agents/skills/awa-usage/SKILL.md +3 -0
  17. package/templates/awa/.awa/.agent/schemas/ALIGN_REPORT.schema.yaml +83 -0
  18. package/templates/awa/.awa/.agent/schemas/API.schema.yaml +7 -0
  19. package/templates/awa/.awa/.agent/schemas/ARCHITECTURE.schema.yaml +260 -0
  20. package/templates/awa/.awa/.agent/schemas/DESIGN.schema.yaml +361 -0
  21. package/templates/awa/.awa/.agent/schemas/EXAMPLES.schema.yaml +98 -0
  22. package/templates/awa/.awa/.agent/schemas/FEAT.schema.yaml +143 -0
  23. package/templates/awa/.awa/.agent/schemas/PLAN.schema.yaml +151 -0
  24. package/templates/awa/.awa/.agent/schemas/README.schema.yaml +137 -0
  25. package/templates/awa/.awa/.agent/schemas/REQ.schema.yaml +169 -0
  26. package/templates/awa/.awa/.agent/schemas/TASK.schema.yaml +200 -0
  27. package/templates/awa/.claude/agents/awa.md +2 -2
  28. package/templates/awa/.claude/skills/awa-align/SKILL.md +3 -0
  29. package/templates/awa/.claude/skills/awa-check/SKILL.md +4 -0
  30. package/templates/awa/.claude/skills/awa-usage/SKILL.md +3 -0
  31. package/templates/awa/.codex/prompts/awa-align.md +3 -0
  32. package/templates/awa/.codex/prompts/awa-check.md +4 -0
  33. package/templates/awa/.cursor/rules/awa-agent.md +1 -1
  34. package/templates/awa/.cursor/rules/awa-align.md +8 -0
  35. package/templates/awa/.cursor/rules/awa-check.md +9 -0
  36. package/templates/awa/.gemini/commands/awa-align.md +3 -0
  37. package/templates/awa/.gemini/commands/awa-check.md +4 -0
  38. package/templates/awa/.gemini/skills/awa-align/SKILL.md +3 -0
  39. package/templates/awa/.gemini/skills/awa-check/SKILL.md +4 -0
  40. package/templates/awa/.gemini/skills/awa-usage/SKILL.md +3 -0
  41. package/templates/awa/.github/agents/awa.agent.md +2 -2
  42. package/templates/awa/.github/prompts/awa.align.prompt.md +8 -0
  43. package/templates/awa/.github/prompts/awa.check.prompt.md +9 -0
  44. package/templates/awa/.github/skills/awa-align/SKILL.md +8 -0
  45. package/templates/awa/.github/skills/awa-check/SKILL.md +9 -0
  46. package/templates/awa/.github/skills/awa-usage/SKILL.md +8 -0
  47. package/templates/awa/.kilocode/rules/awa-agent.md +1 -1
  48. package/templates/awa/.kilocode/skills/awa-align/SKILL.md +3 -0
  49. package/templates/awa/.kilocode/skills/awa-check/SKILL.md +4 -0
  50. package/templates/awa/.kilocode/skills/awa-usage/SKILL.md +3 -0
  51. package/templates/awa/.kilocode/workflows/awa-align.md +3 -0
  52. package/templates/awa/.kilocode/workflows/awa-check.md +4 -0
  53. package/templates/awa/.opencode/agents/awa.md +2 -2
  54. package/templates/awa/.opencode/commands/awa-align.md +3 -0
  55. package/templates/awa/.opencode/commands/awa-check.md +4 -0
  56. package/templates/awa/.opencode/skills/awa-align/SKILL.md +3 -0
  57. package/templates/awa/.opencode/skills/awa-check/SKILL.md +4 -0
  58. package/templates/awa/.opencode/skills/awa-usage/SKILL.md +3 -0
  59. package/templates/awa/.qwen/commands/awa-align.md +3 -0
  60. package/templates/awa/.qwen/commands/awa-check.md +4 -0
  61. package/templates/awa/.qwen/skills/awa-align/SKILL.md +3 -0
  62. package/templates/awa/.qwen/skills/awa-check/SKILL.md +4 -0
  63. package/templates/awa/.qwen/skills/awa-usage/SKILL.md +3 -0
  64. package/templates/awa/.roo/rules/awa-agent.md +1 -1
  65. package/templates/awa/.roo/skills/awa-align/SKILL.md +3 -0
  66. package/templates/awa/.roo/skills/awa-check/SKILL.md +4 -0
  67. package/templates/awa/.roo/skills/awa-usage/SKILL.md +3 -0
  68. package/templates/awa/.windsurf/rules/awa-agent.md +1 -1
  69. package/templates/awa/.windsurf/skills/awa-align/SKILL.md +3 -0
  70. package/templates/awa/.windsurf/skills/awa-check/SKILL.md +4 -0
  71. package/templates/awa/.windsurf/skills/awa-usage/SKILL.md +3 -0
  72. package/templates/awa/AGENTS.md +1 -1
  73. package/templates/awa/CLAUDE.md +1 -1
  74. package/templates/awa/GEMINI.md +1 -1
  75. package/templates/awa/QWEN.md +1 -1
  76. package/templates/awa/_README.md +3 -2
  77. package/templates/awa/_delete.txt +49 -0
  78. package/templates/awa/_partials/{_cmd.awa-validate-alignment.md → _cmd.awa-align.md} +1 -1
  79. package/templates/awa/_partials/_cmd.awa-check.md +6 -0
  80. package/templates/awa/_partials/_skill.awa-align.md +6 -0
  81. package/templates/awa/_partials/_skill.awa-check.md +6 -0
  82. package/templates/awa/_partials/_skill.awa-usage.md +6 -0
  83. package/templates/awa/_partials/{awa.validate-alignment.md → awa.align.md} +2 -2
  84. package/templates/awa/_partials/awa.architecture.md +1 -1
  85. package/templates/awa/_partials/awa.check.md +73 -0
  86. package/templates/awa/_partials/awa.code.md +1 -0
  87. package/templates/awa/_partials/awa.core.md +24 -10
  88. package/templates/awa/_partials/awa.design.md +3 -2
  89. package/templates/awa/_partials/awa.documentation.md +1 -1
  90. package/templates/awa/_partials/awa.examples.md +1 -1
  91. package/templates/awa/_partials/awa.feature.md +1 -1
  92. package/templates/awa/_partials/awa.plan.md +1 -1
  93. package/templates/awa/_partials/awa.refactor.md +1 -0
  94. package/templates/awa/_partials/awa.requirements.md +2 -1
  95. package/templates/awa/_partials/awa.tasks.md +3 -3
  96. package/templates/awa/_partials/awa.upgrade.md +13 -12
  97. package/templates/awa/_partials/awa.usage.md +265 -0
  98. package/templates/awa/_tests/claude.toml +7 -0
  99. package/templates/awa/_tests/copilot.toml +6 -0
  100. package/templates/awa/.agent/skills/awa-validate-alignment/SKILL.md +0 -3
  101. package/templates/awa/.agent/workflows/awa-validate-alignment.md +0 -3
  102. package/templates/awa/.agents/skills/awa-validate-alignment/SKILL.md +0 -3
  103. package/templates/awa/.awa/.agent/schemas/ALIGN_REPORT.schema.md +0 -156
  104. package/templates/awa/.awa/.agent/schemas/API.schema.md +0 -4
  105. package/templates/awa/.awa/.agent/schemas/ARCHITECTURE.schema.md +0 -176
  106. package/templates/awa/.awa/.agent/schemas/DESIGN.schema.md +0 -253
  107. package/templates/awa/.awa/.agent/schemas/EXAMPLES.schema.md +0 -51
  108. package/templates/awa/.awa/.agent/schemas/FEAT.schema.md +0 -61
  109. package/templates/awa/.awa/.agent/schemas/PLAN.schema.md +0 -8
  110. package/templates/awa/.awa/.agent/schemas/README.schema.md +0 -133
  111. package/templates/awa/.awa/.agent/schemas/REQ.schema.md +0 -125
  112. package/templates/awa/.awa/.agent/schemas/TASK.schema.md +0 -137
  113. package/templates/awa/.claude/skills/awa-validate-alignment/SKILL.md +0 -3
  114. package/templates/awa/.codex/prompts/awa-validate-alignment.md +0 -3
  115. package/templates/awa/.cursor/rules/awa-validate-alignment.md +0 -8
  116. package/templates/awa/.gemini/commands/awa-validate-alignment.md +0 -3
  117. package/templates/awa/.gemini/skills/awa-validate-alignment/SKILL.md +0 -3
  118. package/templates/awa/.github/prompts/awa.validate-alignment.prompt.md +0 -8
  119. package/templates/awa/.github/skills/awa-validate-alignment/SKILL.md +0 -8
  120. package/templates/awa/.kilocode/skills/awa-validate-alignment/SKILL.md +0 -3
  121. package/templates/awa/.kilocode/workflows/awa-validate-alignment.md +0 -3
  122. package/templates/awa/.opencode/commands/awa-validate-alignment.md +0 -3
  123. package/templates/awa/.opencode/skills/awa-validate-alignment/SKILL.md +0 -3
  124. package/templates/awa/.qwen/commands/awa-validate-alignment.md +0 -3
  125. package/templates/awa/.qwen/skills/awa-validate-alignment/SKILL.md +0 -3
  126. package/templates/awa/.roo/skills/awa-validate-alignment/SKILL.md +0 -3
  127. package/templates/awa/.windsurf/skills/awa-validate-alignment/SKILL.md +0 -3
  128. package/templates/awa/_partials/_skill.awa-validate-alignment.md +0 -6
@@ -0,0 +1,151 @@
1
+ # Structural rules for PLAN-{nnn}-{plan-name}.md files
2
+ target-files: ".awa/plans/PLAN-*.md"
3
+ description: >
4
+ Ad-hoc plan for features, improvements, refactors, or other work.
5
+ Succinct language. Break down work into actionable steps (checkbox items).
6
+ Status and direction metadata required. Structure is flexible —
7
+ organize sections as the plan demands. Plans should not contain significant
8
+ code (short snippets for explanation are fine).
9
+ Traceability links to REQ/DESIGN/code/tests are optional but encouraged.
10
+ line-limit: 500
11
+
12
+ sections:
13
+ # H1 title with status/direction metadata
14
+ - heading: ".*"
15
+ level: 1
16
+ required: true
17
+ description: >
18
+ Plan title. Descriptive but concise (e.g., "Refactor Config Loader",
19
+ "Add Diff Preview Feature"). Followed immediately by STATUS and
20
+ DIRECTION metadata lines, and optional TRACEABILITY links.
21
+ contains:
22
+ - pattern: "^STATUS:"
23
+ label: "STATUS declaration"
24
+ description: >
25
+ Current plan status. One of: in-progress, completed, blocked.
26
+ Format: STATUS: in-progress
27
+ - pattern: "^DIRECTION:"
28
+ label: "DIRECTION declaration"
29
+ description: >
30
+ Workflow direction for this plan. One of: top-down (architecture
31
+ first), bottom-up (implementation first), lateral (cross-cutting).
32
+ Format: DIRECTION: top-down
33
+
34
+ # Context section (optional)
35
+ - heading: "Context"
36
+ level: 2
37
+ description: >
38
+ Why this plan exists. What problem or goal it addresses.
39
+ Brief — one or two paragraphs. Reference FEAT/REQ docs if they exist
40
+ rather than restating.
41
+
42
+ # Steps section (optional — steps may also appear in domain-specific H2s)
43
+ - heading: "Steps"
44
+ level: 2
45
+ description: >
46
+ Actionable steps as checkbox items. The core of the plan.
47
+ Format: - [ ] Step description
48
+ Mark completed steps with [x]. Group with H3 subsections if needed.
49
+ Each step should be concrete and verifiable.
50
+
51
+ # Risks section (optional)
52
+ - heading: "Risks"
53
+ level: 2
54
+ description: >
55
+ Known risks, unknowns, or potential blockers. Bullet list.
56
+ Include mitigation strategies where possible.
57
+
58
+ # Dependencies section (optional)
59
+ - heading: "Dependencies"
60
+ level: 2
61
+ description: >
62
+ Prerequisites or upstream work that must complete first.
63
+ Reference other plans, tasks, or external factors.
64
+
65
+ # Completion Criteria section (optional)
66
+ - heading: "Completion Criteria"
67
+ level: 2
68
+ description: >
69
+ How to know when this plan is done. Concrete, verifiable conditions.
70
+ Format: - [ ] Criterion description
71
+
72
+ # Open Questions section (optional)
73
+ - heading: "Open Questions"
74
+ level: 2
75
+ description: >
76
+ Unresolved questions needing clarification from the user or team.
77
+ Format: - [ ] Question (resolved questions marked [x] with answer).
78
+
79
+ # References section (optional)
80
+ - heading: "References"
81
+ level: 2
82
+ description: >
83
+ Links to related artifacts: REQ, DESIGN, TASK, FEAT, code files,
84
+ external docs. Format: - {artifact}: {path or description}
85
+
86
+ # Change Log section (optional)
87
+ - heading: "Change Log"
88
+ level: 2
89
+ description: "Version history. Format: - {version} ({date}): {changes}"
90
+
91
+ sections-prohibited:
92
+ - "**"
93
+
94
+ example: |
95
+ # Refactor Config Loader
96
+
97
+ STATUS: in-progress
98
+ DIRECTION: bottom-up
99
+ TRACEABILITY: REQ-CFG-config.md, DESIGN-CFG-config.md
100
+
101
+ ## Context
102
+
103
+ The config loader has grown organically and now mixes parsing, validation,
104
+ and merging in a single function. This makes it hard to test and extend.
105
+ Split into discrete pipeline stages.
106
+
107
+ ## Steps
108
+
109
+ - [x] Extract TOML parsing into standalone function
110
+ - [x] Extract validation into ConfigValidator
111
+ - [ ] Extract merge logic into ConfigMerger
112
+ - [ ] Update all call sites to use new pipeline
113
+ - [ ] Remove old monolithic load function
114
+
115
+ ### Testing
116
+
117
+ - [ ] Add property tests for ConfigMerger (CLI overrides file)
118
+ - [ ] Add unit tests for ConfigValidator edge cases
119
+ - [ ] Verify integration test still passes end-to-end
120
+
121
+ ## Risks
122
+
123
+ - Merge logic has implicit ordering assumptions that may break when extracted
124
+ - Call sites in CLI layer may depend on intermediate state
125
+
126
+ ## Dependencies
127
+
128
+ - TASK-CFG-config-001.md Phase 3 must be complete (defines the types)
129
+
130
+ ## Completion Criteria
131
+
132
+ - [ ] All existing tests pass
133
+ - [ ] New property tests cover merge invariants
134
+ - [ ] No function exceeds 40 lines
135
+ - [ ] Config pipeline is documented in DESIGN
136
+
137
+ ## Open Questions
138
+
139
+ - [x] Should validation happen before or after merge? — After merge (validate final state)
140
+ - [ ] Do we need a separate error type for merge failures?
141
+
142
+ ## References
143
+
144
+ - REQ: .awa/specs/REQ-CFG-config.md
145
+ - DESIGN: .awa/specs/DESIGN-CFG-config.md
146
+ - Code: src/core/config.ts
147
+
148
+ ## Change Log
149
+
150
+ - 001 (2025-06-15): Initial plan
151
+ - 002 (2025-06-18): Completed parsing extraction
@@ -0,0 +1,137 @@
1
+ # Structural rules for README.md
2
+ target-files: "README.md"
3
+ description: >
4
+ Project README. Succinct, user-facing language. Link to detailed docs in
5
+ /docs folder rather than including lengthy content inline. Required sections:
6
+ title, description, installation, and usage. Keep it concise — the README
7
+ is the front door, not the whole house.
8
+ line-limit: 500
9
+
10
+ sections:
11
+ # Project title (H1)
12
+ - heading: ".*"
13
+ level: 1
14
+ required: true
15
+ description: >
16
+ Project name as H1. Optionally followed by badge images and a one-paragraph
17
+ description of what the project does and why it exists.
18
+
19
+ # Features section (optional)
20
+ - heading: "Features"
21
+ level: 2
22
+ description: "Bullet list of key features. Keep to 5-10 items."
23
+
24
+ # Installation section
25
+ - heading: "Installation"
26
+ level: 2
27
+ required: true
28
+ description: >
29
+ How to install the project. May contain Prerequisites and Install
30
+ subsections. Include code blocks with shell commands.
31
+ contains:
32
+ - code-block: true
33
+ label: "install command"
34
+ description: "Shell command(s) to install the project."
35
+
36
+ # Usage section
37
+ - heading: "Usage"
38
+ level: 2
39
+ required: true
40
+ description: >
41
+ Quick start example showing minimal usage. Include at least one code block.
42
+ Additional examples can be H3 subsections.
43
+ contains:
44
+ - code-block: true
45
+ label: "usage example"
46
+ description: "Code block demonstrating basic usage."
47
+
48
+ # Documentation section (optional)
49
+ - heading: "Documentation"
50
+ level: 2
51
+ description: >
52
+ Links to detailed documentation in /docs folder.
53
+ Format: - [Title](docs/file.md) - Description
54
+
55
+ # Contributing section (optional)
56
+ - heading: "Contributing"
57
+ level: 2
58
+ description: "Brief instructions or link to CONTRIBUTING.md."
59
+
60
+ # License section (optional)
61
+ - heading: "License"
62
+ level: 2
63
+ description: "License name and link to LICENSE file."
64
+
65
+ # Acknowledgments section (optional)
66
+ - heading: "Acknowledgments"
67
+ level: 2
68
+ description: "Credits to libraries, tools, or contributors."
69
+
70
+ example: |
71
+ # awa CLI
72
+
73
+ [![npm version](https://img.shields.io/npm/v/awa-cli.svg)](https://www.npmjs.com/package/awa-cli)
74
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
75
+
76
+ awa CLI generates AI coding agent configuration files from templates, enabling developers to quickly scaffold consistent agent setups across projects.
77
+
78
+ ## Features
79
+
80
+ - Template-based configuration generation
81
+ - Feature flag support for conditional content
82
+ - Multiple output formats (Markdown, YAML, JSON)
83
+ - Diff mode to preview changes before applying
84
+ - Local and remote template sources
85
+
86
+ ## Installation
87
+
88
+ ### Prerequisites
89
+
90
+ - Node.js 20 or higher
91
+ - npm or pnpm
92
+
93
+ ### Install
94
+
95
+ ```bash
96
+ npm install -g awa-cli
97
+ ```
98
+
99
+ ## Usage
100
+
101
+ ```bash
102
+ # Generate configuration from default template
103
+ awa generate
104
+
105
+ # Generate with specific features enabled
106
+ awa generate --features typescript,testing
107
+
108
+ # Preview changes without writing files
109
+ awa diff
110
+ ```
111
+
112
+ ### Examples
113
+
114
+ #### Custom Template
115
+
116
+ ```bash
117
+ awa generate --template ./my-templates --output ./.ai
118
+ ```
119
+
120
+ ## Documentation
121
+
122
+ - [Configuration Guide](docs/configuration.md) — Configure templates and options
123
+ - [Template Authoring](docs/templates.md) — Create custom templates
124
+ - [CLI Reference](docs/cli-reference.md) — Complete command documentation
125
+
126
+ ## Contributing
127
+
128
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
129
+
130
+ ## License
131
+
132
+ [MIT](LICENSE)
133
+
134
+ ## Acknowledgments
135
+
136
+ - Eta templating engine
137
+ - Citty CLI framework
@@ -0,0 +1,169 @@
1
+ # Structural rules for REQ-{CODE}-{feature-name}.md files
2
+ target-files: ".awa/specs/REQ-*.md"
3
+ description: >
4
+ Requirements specification using EARS (Easy Approach to Requirements Syntax).
5
+ Succinct language. Do not overspecify. Omit irrelevant information.
6
+ Each requirement has an ID ({CODE}-{n}), a user story (AS A/I WANT/SO THAT),
7
+ and acceptance criteria with INCOSE-compliant types.
8
+ Subrequirements use dotted IDs ({CODE}-{n}.{p}).
9
+ line-limit: 500
10
+
11
+ sections:
12
+ # Top-level heading: "Requirements Specification"
13
+ - heading: "Requirements Specification"
14
+ level: 1
15
+ required: true
16
+ description: "Document title. No metadata in this section."
17
+
18
+ # Introduction section
19
+ - heading: "Introduction"
20
+ level: 2
21
+ required: true
22
+ description: "Brief context for the requirements. One or two paragraphs."
23
+
24
+ # Glossary section (optional)
25
+ - heading: "Glossary"
26
+ level: 2
27
+ description: >
28
+ Domain terms in TERM: definition format. Use CAPITALS for term names.
29
+ Format: - TERM: Definition
30
+
31
+ # Stakeholders section (optional)
32
+ - heading: "Stakeholders"
33
+ level: 2
34
+ description: >
35
+ Roles that interact with or are affected by this feature.
36
+ Format: - ROLE: Description
37
+
38
+ # Requirements section with repeatable requirement headings
39
+ - heading: "Requirements"
40
+ level: 2
41
+ required: true
42
+ description: >
43
+ Container for all requirements. Each child heading is a requirement
44
+ with ID, title, optional priority, user story, and acceptance criteria.
45
+ children:
46
+ - heading: "[A-Z]+-\\d+.*"
47
+ level: 3
48
+ required: true
49
+ repeatable: true
50
+ description: >
51
+ Individual requirement heading. Format: ### {CODE}-{n}: Title [{PRIORITY}]
52
+ where PRIORITY is MUST, SHOULD, COULD, or WONT (optional).
53
+ Contains a user story, optional rationale blockquote, ACCEPTANCE CRITERIA
54
+ heading, AC items, and optional DEPENDS ON line.
55
+ contains:
56
+ # User story format
57
+ - pattern: "AS A .*, I WANT .*, SO THAT"
58
+ label: "user story"
59
+ description: >
60
+ User story in AS A {role}, I WANT {want}, SO THAT {benefit} format.
61
+ One sentence. Role, want, and benefit are all required.
62
+ # Acceptance criteria heading
63
+ - pattern: "ACCEPTANCE CRITERIA"
64
+ label: "AC heading"
65
+ description: "Literal text ACCEPTANCE CRITERIA (no markdown heading, just text)."
66
+ # At least one AC item
67
+ - list:
68
+ pattern: "_AC-\\d+\\s*\\[(ubiquitous|event|state|conditional|optional|complex)\\]"
69
+ min: 1
70
+ label: "acceptance criteria items"
71
+ description: >
72
+ Acceptance criteria items. Format:
73
+ - {CODE}-{n}_AC-{m} [{type}]: {statement} - {notes}
74
+ Types (EARS/INCOSE):
75
+ - ubiquitous: always true, no trigger ("The system SHALL ...")
76
+ - event: triggered by a stimulus ("WHEN x THEN system SHALL ...")
77
+ - state: true while a condition holds ("WHILE x THE system SHALL ...")
78
+ - conditional: depends on a boolean condition ("IF x THEN system SHALL ...")
79
+ - optional: feature activated by trigger ("WHERE x IS ENABLED THE system SHALL ...")
80
+ - complex: combines multiple EARS patterns
81
+
82
+ # Assumptions section (optional)
83
+ - heading: "Assumptions"
84
+ level: 2
85
+ description: "Bullet list of assumptions underlying the requirements."
86
+
87
+ # Constraints section (optional)
88
+ - heading: "Constraints"
89
+ level: 2
90
+ description: "Bullet list of constraints on the implementation."
91
+
92
+ # Out of Scope section (optional)
93
+ - heading: "Out of Scope"
94
+ level: 2
95
+ description: "Bullet list of explicitly excluded functionality."
96
+
97
+ # Change Log section (optional)
98
+ - heading: "Change Log"
99
+ level: 2
100
+ description: "Version history. Format: - {version} ({date}): {changes}"
101
+
102
+ sections-prohibited:
103
+ - "**"
104
+
105
+ example: |
106
+ # Requirements Specification
107
+
108
+ ## Introduction
109
+
110
+ Core engine requirements for game framework.
111
+
112
+ ## Glossary
113
+
114
+ - GAME LOOP: Core cycle of update-render that drives the engine
115
+ - CONTEXT: Runtime state container for engine subsystems
116
+
117
+ ## Stakeholders
118
+
119
+ - GAME DEVELOPER: Builds games using the engine API
120
+ - ENGINE MAINTAINER: Maintains and extends engine internals
121
+
122
+ ## Requirements
123
+
124
+ ### ENG-1: Core Engine Framework [MUST]
125
+
126
+ AS A game developer, I WANT a game loop, SO THAT predictable execution.
127
+
128
+ > Foundation for all games.
129
+
130
+ ACCEPTANCE CRITERIA
131
+
132
+ - ENG-1_AC-1 [event]: WHEN engine initializes THEN system SHALL create context
133
+ - ENG-1_AC-2 [event]: WHEN `--verbose` flag is provided THEN system SHALL enable debug logging
134
+ - ENG-1_AC-3 [ubiquitous]: The system SHALL maintain 60fps minimum frame rate
135
+
136
+ ### ENG-1.1: Subsystem Registration [SHOULD]
137
+
138
+ AS A engine maintainer, I WANT subsystems to self-register, SO THAT modular architecture.
139
+
140
+ ACCEPTANCE CRITERIA
141
+
142
+ - ENG-1.1_AC-1 [event]: WHEN subsystem loads THEN it SHALL register with context
143
+
144
+ ### ENG-2: Resource Management [MUST]
145
+
146
+ AS A game developer, I WANT automatic resource loading, SO THAT simplified asset management.
147
+
148
+ ACCEPTANCE CRITERIA
149
+
150
+ - ENG-2_AC-1 [event]: WHEN resource requested THEN system SHALL load asynchronously
151
+ - ENG-2_AC-2 [ubiquitous]: The system SHALL cache loaded resources
152
+
153
+ DEPENDS ON: ENG-1
154
+
155
+ ## Assumptions
156
+
157
+ - Target platform supports OpenGL 3.3 or higher
158
+
159
+ ## Constraints
160
+
161
+ - Must run on Windows, macOS, and Linux
162
+
163
+ ## Out of Scope
164
+
165
+ - Mobile platform support
166
+
167
+ ## Change Log
168
+
169
+ - 1.0.0 (2025-01-10): Initial requirements
@@ -0,0 +1,200 @@
1
+ # Structural rules for TASK-{CODE}-{feature-name}-{nnn}.md files
2
+ target-files: ".awa/tasks/TASK-*.md"
3
+ description: >
4
+ Implementation tasks only. Dependency-ordered. Traceable to REQ and DESIGN.
5
+ Each task has an ID (T-{CODE}-{nnn}), a description, and a target file path.
6
+ Phases group tasks by execution order; requirement phases carry [MUST]/[SHOULD]/[COULD]
7
+ priority markers and include GOAL, TEST CRITERIA, IMPLEMENTS, and TESTS lines.
8
+ Setup/foundation/polish phases must NOT include IMPLEMENTS or TESTS.
9
+ line-limit: 500
10
+
11
+ sections:
12
+ # Top-level heading: "Implementation Tasks"
13
+ - heading: "Implementation Tasks"
14
+ level: 1
15
+ required: true
16
+ description: >
17
+ Document title. Followed by FEATURE (name from REQ) and SOURCE
18
+ (comma-separated paths to REQ and DESIGN files).
19
+ contains:
20
+ - pattern: "^FEATURE:"
21
+ label: "FEATURE declaration"
22
+ description: "Feature name this task list implements (from REQ)."
23
+ - pattern: "^SOURCE:"
24
+ label: "SOURCE declaration"
25
+ description: "Comma-separated paths to the REQ and DESIGN source files."
26
+
27
+ # Phase headings: "## Phase N: Name [PRIORITY]"
28
+ - heading: "Phase \\d+:.*"
29
+ level: 2
30
+ required: true
31
+ repeatable: true
32
+ description: >
33
+ Numbered phases in execution order. Requirement phases append a priority
34
+ marker: [MUST], [SHOULD], or [COULD]. Setup/foundation/polish phases
35
+ have no priority marker. Each phase contains checkbox task items.
36
+ contains:
37
+ # Tasks as checkbox items: "- [ ] T-{CODE}-{nnn} ... → path"
38
+ - list:
39
+ pattern: "\\[ \\] T-[A-Z][A-Z0-9]*-\\d+"
40
+ min: 1
41
+ label: "task checkbox items"
42
+ description: >
43
+ Task items as unchecked checkboxes. Format:
44
+ - [ ] T-{CODE}-{nnn} [P]? [{CODE}-{n}]? Description → target/path.
45
+ [P] marks parallelizable tasks. [{CODE}-{n}] is the requirement ID
46
+ (only on requirement phases). Always unchecked in generated output.
47
+ # Tasks must have file path targets (→)
48
+ - pattern: "→"
49
+ label: "file path targets"
50
+ description: "Every task line must include → followed by the target file path."
51
+ # GOAL required on requirement phases (those with [MUST], [SHOULD], [COULD])
52
+ - pattern: "^GOAL:"
53
+ label: "GOAL statement"
54
+ description: "One-line goal for the phase, derived from the requirement's user story."
55
+ when:
56
+ heading-matches: "\\[(MUST|SHOULD|COULD)\\]"
57
+ # TEST CRITERIA required on requirement phases
58
+ - pattern: "^TEST CRITERIA:"
59
+ label: "TEST CRITERIA statement"
60
+ description: "How to verify the phase is complete."
61
+ when:
62
+ heading-matches: "\\[(MUST|SHOULD|COULD)\\]"
63
+ # IMPLEMENTS forbidden on setup/foundation/polish phases (no priority marker)
64
+ - pattern: "IMPLEMENTS:"
65
+ prohibited: true
66
+ label: "IMPLEMENTS trace line (not allowed in setup/polish phases)"
67
+ description: >
68
+ IMPLEMENTS: {CODE}-{n}[.{p}]_AC-{m} — traces a task to the AC it implements.
69
+ Only allowed on requirement phases (those with a priority marker).
70
+ when:
71
+ heading-not-matches: "\\[(MUST|SHOULD|COULD)\\]"
72
+ # TESTS forbidden on setup/foundation/polish phases
73
+ - pattern: "TESTS:"
74
+ prohibited: true
75
+ label: "TESTS trace line (not allowed in setup/polish phases)"
76
+ description: >
77
+ TESTS: {CODE}_P-{n} or {CODE}-{n}[.{p}]_AC-{m} — traces a task to the
78
+ property or AC it tests. Only allowed on requirement phases.
79
+ when:
80
+ heading-not-matches: "\\[(MUST|SHOULD|COULD)\\]"
81
+ # Requirement labels forbidden on setup/foundation/polish phases
82
+ - pattern: "\\[[A-Z]+-\\d+\\]"
83
+ prohibited: true
84
+ label: "requirement label (not allowed in setup/polish phases)"
85
+ description: >
86
+ [{CODE}-{n}] requirement labels are only allowed on requirement phases
87
+ (those with a priority marker like [MUST], [SHOULD], [COULD]).
88
+ when:
89
+ heading-not-matches: "\\[(MUST|SHOULD|COULD)\\]"
90
+
91
+ # Dependencies section
92
+ - heading: "Dependencies"
93
+ level: 2
94
+ required: true
95
+ description: >
96
+ Lists inter-requirement dependencies. Format:
97
+ {CODE}-{n} → {CODE}-{n} (reason) or {CODE}-{n} → (none).
98
+
99
+ # Parallel Opportunities section
100
+ - heading: "Parallel Opportunities"
101
+ level: 2
102
+ required: true
103
+ description: >
104
+ Identifies tasks within each phase that can execute concurrently.
105
+ Format: Phase N: T-{CODE}-{nnn}, T-{CODE}-{nnn} can run parallel after T-{CODE}-{nnn}.
106
+
107
+ # Requirements Traceability section
108
+ - heading: "Requirements Traceability"
109
+ level: 2
110
+ required: true
111
+ description: >
112
+ Trace matrix grouped by source REQ file. Each H3 is a REQ file path,
113
+ containing bullet entries mapping ACs to tasks and tests, followed by
114
+ properties to tests. Ends with UNCOVERED listing any ACs or properties
115
+ without task/test coverage.
116
+ children:
117
+ - heading: ".*"
118
+ level: 3
119
+ repeatable: true
120
+ required: true
121
+ description: >
122
+ Source REQ file heading. Format: ### REQ-{CODE}-{feature}.md
123
+ Followed by bullet list of AC and property trace entries.
124
+ AC format: - {AC-ID} → {Task} ({Test})
125
+ Property format: - {Property-ID} → {Test}
126
+ contains:
127
+ - pattern: "^UNCOVERED:"
128
+ label: "UNCOVERED declaration"
129
+ description: "Lists AC or property IDs that lack task/test coverage, or (none)."
130
+
131
+ sections-prohibited:
132
+ - "**"
133
+
134
+ example: |
135
+ # Implementation Tasks
136
+
137
+ FEATURE: Configuration System
138
+ SOURCE: REQ-CFG-config.md, DESIGN-CFG-config.md
139
+
140
+ ## Phase 1: Setup
141
+
142
+ - [ ] T-CFG-001 Initialize module structure → src/config/
143
+ - [ ] T-CFG-002 [P] Add dependencies (smol-toml) → package.json
144
+
145
+ ## Phase 2: Foundation
146
+
147
+ - [ ] T-CFG-003 Define Config and RawConfig types → src/config/types.ts
148
+ - [ ] T-CFG-004 Define ConfigError variants → src/config/errors.ts
149
+
150
+ ## Phase 3: Config Loading [MUST]
151
+
152
+ GOAL: Load and merge configuration from file with defaults
153
+ TEST CRITERIA: Can load valid TOML, missing keys get defaults
154
+
155
+ - [ ] T-CFG-010 [CFG-1] Implement load function → src/config/loader.ts
156
+ IMPLEMENTS: CFG-1_AC-1
157
+ - [ ] T-CFG-011 [CFG-1] Implement merge function → src/config/loader.ts
158
+ IMPLEMENTS: CFG-1_AC-2
159
+ - [ ] T-CFG-012 [P] [CFG-1] Property test for default preservation → tests/config/loader.test.ts
160
+ TESTS: CFG_P-1
161
+ - [ ] T-CFG-013 [P] [CFG-1] Test load from valid path → tests/config/loader.test.ts
162
+ TESTS: CFG-1_AC-1
163
+
164
+ ## Phase 4: Config Validation [SHOULD]
165
+
166
+ GOAL: Validate loaded config against schema
167
+ TEST CRITERIA: Invalid config rejected with clear error
168
+
169
+ - [ ] T-CFG-020 [CFG-2] Implement validate function → src/config/validator.ts
170
+ IMPLEMENTS: CFG-2_AC-1
171
+ - [ ] T-CFG-021 [P] [CFG-2] Test schema validation → tests/config/validator.test.ts
172
+ TESTS: CFG-2_AC-1
173
+
174
+ ## Phase 5: Polish
175
+
176
+ - [ ] T-CFG-030 Integration test: load → validate → use → tests/config/integration.test.ts
177
+ TESTS: CFG-1_AC-1, CFG-2_AC-1
178
+
179
+ ---
180
+
181
+ ## Dependencies
182
+
183
+ CFG-1 → (none)
184
+ CFG-2 → CFG-1 (validates loaded config)
185
+
186
+ ## Parallel Opportunities
187
+
188
+ Phase 3: T-CFG-012, T-CFG-013 can run parallel after T-CFG-011
189
+ Phase 4: T-CFG-021 can run parallel with T-CFG-020
190
+
191
+ ## Requirements Traceability
192
+
193
+ ### REQ-CFG-config.md
194
+
195
+ - CFG-1_AC-1 → T-CFG-010 (T-CFG-013)
196
+ - CFG-1_AC-2 → T-CFG-011 (T-CFG-012)
197
+ - CFG-2_AC-1 → T-CFG-020 (T-CFG-021)
198
+ - CFG_P-1 → T-CFG-012
199
+
200
+ UNCOVERED: (none)
@@ -1,7 +1,7 @@
1
1
  <% if (it.features.includes('claude')) { %>
2
2
  ---
3
3
  name: awa
4
- description: "awa 0.2.0"
4
+ description: "awa <%= it.version %>"
5
5
  ---
6
6
 
7
7
  <%~ include('_partials/awa.core.md', it) %>
@@ -9,6 +9,6 @@ description: "awa 0.2.0"
9
9
  <tool name="read_file">
10
10
  <read path=".awa/rules/*.md" required="true" />
11
11
  <read path=".awa/specs/ARCHITECTURE.md" required="true" />
12
- <read path=".awa/.agent/schemas/*.schema.md" required="before writing corresponding file type" />
12
+ <read path=".awa/.agent/schemas/*.schema.yaml" required="before writing corresponding file type" />
13
13
  </tool>
14
14
  <% } %>
@@ -0,0 +1,3 @@
1
+ <% if (it.features.includes('claude')) { %>
2
+ <%~ include('_partials/_skill.awa-align.md', it) %>
3
+ <% } %>
@@ -0,0 +1,4 @@
1
+ <% if (it.features.includes('claude')) { %>
2
+ <%~ include('_partials/_skill.awa-check.md', it) %>
3
+ <% } %>
4
+
@@ -0,0 +1,3 @@
1
+ <% if (it.features.includes('claude')) { %>
2
+ <%~ include('_partials/_skill.awa-usage.md', it) %>
3
+ <% } %>
@@ -0,0 +1,3 @@
1
+ <% if (it.features.includes('codex')) { %>
2
+ <%~ include('_partials/_cmd.awa-align.md', it) %>
3
+ <% } %>