@ncoderz/awa 0.2.0 → 1.1.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.
- package/README.md +96 -16
- package/dist/index.js +2307 -128
- package/dist/index.js.map +1 -1
- package/package.json +14 -4
- package/templates/awa/.agent/skills/awa-align/SKILL.md +3 -0
- package/templates/awa/.agent/skills/awa-check/SKILL.md +4 -0
- package/templates/awa/.agent/workflows/awa-align.md +3 -0
- package/templates/awa/.agent/workflows/awa-check.md +4 -0
- package/templates/awa/.agents/skills/awa-align/SKILL.md +3 -0
- package/templates/awa/.agents/skills/awa-check/SKILL.md +4 -0
- package/templates/awa/.awa/.agent/schemas/ALIGN_REPORT.schema.yaml +83 -0
- package/templates/awa/.awa/.agent/schemas/API.schema.yaml +7 -0
- package/templates/awa/.awa/.agent/schemas/ARCHITECTURE.schema.yaml +260 -0
- package/templates/awa/.awa/.agent/schemas/DESIGN.schema.yaml +361 -0
- package/templates/awa/.awa/.agent/schemas/EXAMPLES.schema.yaml +98 -0
- package/templates/awa/.awa/.agent/schemas/FEAT.schema.yaml +143 -0
- package/templates/awa/.awa/.agent/schemas/PLAN.schema.yaml +151 -0
- package/templates/awa/.awa/.agent/schemas/README.schema.yaml +137 -0
- package/templates/awa/.awa/.agent/schemas/REQ.schema.yaml +169 -0
- package/templates/awa/.awa/.agent/schemas/TASK.schema.yaml +200 -0
- package/templates/awa/.claude/agents/awa.md +2 -2
- package/templates/awa/.claude/skills/awa-align/SKILL.md +3 -0
- package/templates/awa/.claude/skills/awa-check/SKILL.md +4 -0
- package/templates/awa/.codex/prompts/awa-align.md +3 -0
- package/templates/awa/.codex/prompts/awa-check.md +4 -0
- package/templates/awa/.cursor/rules/awa-agent.md +1 -1
- package/templates/awa/.cursor/rules/awa-align.md +8 -0
- package/templates/awa/.cursor/rules/awa-check.md +9 -0
- package/templates/awa/.gemini/commands/awa-align.md +3 -0
- package/templates/awa/.gemini/commands/awa-check.md +4 -0
- package/templates/awa/.gemini/skills/awa-align/SKILL.md +3 -0
- package/templates/awa/.gemini/skills/awa-check/SKILL.md +4 -0
- package/templates/awa/.github/agents/awa.agent.md +2 -2
- package/templates/awa/.github/prompts/awa.align.prompt.md +8 -0
- package/templates/awa/.github/prompts/awa.check.prompt.md +9 -0
- package/templates/awa/.github/skills/awa-align/SKILL.md +8 -0
- package/templates/awa/.github/skills/awa-check/SKILL.md +9 -0
- package/templates/awa/.kilocode/rules/awa-agent.md +1 -1
- package/templates/awa/.kilocode/skills/awa-align/SKILL.md +3 -0
- package/templates/awa/.kilocode/skills/awa-check/SKILL.md +4 -0
- package/templates/awa/.kilocode/workflows/awa-align.md +3 -0
- package/templates/awa/.kilocode/workflows/awa-check.md +4 -0
- package/templates/awa/.opencode/agents/awa.md +2 -2
- package/templates/awa/.opencode/commands/awa-align.md +3 -0
- package/templates/awa/.opencode/commands/awa-check.md +4 -0
- package/templates/awa/.opencode/skills/awa-align/SKILL.md +3 -0
- package/templates/awa/.opencode/skills/awa-check/SKILL.md +4 -0
- package/templates/awa/.qwen/commands/awa-align.md +3 -0
- package/templates/awa/.qwen/commands/awa-check.md +4 -0
- package/templates/awa/.qwen/skills/awa-align/SKILL.md +3 -0
- package/templates/awa/.qwen/skills/awa-check/SKILL.md +4 -0
- package/templates/awa/.roo/rules/awa-agent.md +1 -1
- package/templates/awa/.roo/skills/awa-align/SKILL.md +3 -0
- package/templates/awa/.roo/skills/awa-check/SKILL.md +4 -0
- package/templates/awa/.windsurf/rules/awa-agent.md +1 -1
- package/templates/awa/.windsurf/skills/awa-align/SKILL.md +3 -0
- package/templates/awa/.windsurf/skills/awa-check/SKILL.md +4 -0
- package/templates/awa/AGENTS.md +1 -1
- package/templates/awa/CLAUDE.md +1 -1
- package/templates/awa/GEMINI.md +1 -1
- package/templates/awa/QWEN.md +1 -1
- package/templates/awa/_README.md +3 -2
- package/templates/awa/_delete.txt +49 -0
- package/templates/awa/_partials/{_cmd.awa-validate-alignment.md → _cmd.awa-align.md} +1 -1
- package/templates/awa/_partials/_cmd.awa-check.md +6 -0
- package/templates/awa/_partials/_skill.awa-align.md +6 -0
- package/templates/awa/_partials/_skill.awa-check.md +6 -0
- package/templates/awa/_partials/{awa.validate-alignment.md → awa.align.md} +2 -2
- package/templates/awa/_partials/awa.architecture.md +1 -1
- package/templates/awa/_partials/awa.check.md +73 -0
- package/templates/awa/_partials/awa.code.md +1 -0
- package/templates/awa/_partials/awa.core.md +24 -10
- package/templates/awa/_partials/awa.design.md +3 -2
- package/templates/awa/_partials/awa.documentation.md +1 -1
- package/templates/awa/_partials/awa.examples.md +1 -1
- package/templates/awa/_partials/awa.feature.md +1 -1
- package/templates/awa/_partials/awa.plan.md +1 -1
- package/templates/awa/_partials/awa.refactor.md +1 -0
- package/templates/awa/_partials/awa.requirements.md +2 -1
- package/templates/awa/_partials/awa.tasks.md +3 -3
- package/templates/awa/_partials/awa.upgrade.md +13 -12
- package/templates/awa/_tests/claude.toml +7 -0
- package/templates/awa/_tests/copilot.toml +6 -0
- package/templates/awa/.agent/skills/awa-validate-alignment/SKILL.md +0 -3
- package/templates/awa/.agent/workflows/awa-validate-alignment.md +0 -3
- package/templates/awa/.agents/skills/awa-validate-alignment/SKILL.md +0 -3
- package/templates/awa/.awa/.agent/schemas/ALIGN_REPORT.schema.md +0 -156
- package/templates/awa/.awa/.agent/schemas/API.schema.md +0 -4
- package/templates/awa/.awa/.agent/schemas/ARCHITECTURE.schema.md +0 -176
- package/templates/awa/.awa/.agent/schemas/DESIGN.schema.md +0 -253
- package/templates/awa/.awa/.agent/schemas/EXAMPLES.schema.md +0 -51
- package/templates/awa/.awa/.agent/schemas/FEAT.schema.md +0 -61
- package/templates/awa/.awa/.agent/schemas/PLAN.schema.md +0 -8
- package/templates/awa/.awa/.agent/schemas/README.schema.md +0 -133
- package/templates/awa/.awa/.agent/schemas/REQ.schema.md +0 -125
- package/templates/awa/.awa/.agent/schemas/TASK.schema.md +0 -137
- package/templates/awa/.claude/skills/awa-validate-alignment/SKILL.md +0 -3
- package/templates/awa/.codex/prompts/awa-validate-alignment.md +0 -3
- package/templates/awa/.cursor/rules/awa-validate-alignment.md +0 -8
- package/templates/awa/.gemini/commands/awa-validate-alignment.md +0 -3
- package/templates/awa/.gemini/skills/awa-validate-alignment/SKILL.md +0 -3
- package/templates/awa/.github/prompts/awa.validate-alignment.prompt.md +0 -8
- package/templates/awa/.github/skills/awa-validate-alignment/SKILL.md +0 -8
- package/templates/awa/.kilocode/skills/awa-validate-alignment/SKILL.md +0 -3
- package/templates/awa/.kilocode/workflows/awa-validate-alignment.md +0 -3
- package/templates/awa/.opencode/commands/awa-validate-alignment.md +0 -3
- package/templates/awa/.opencode/skills/awa-validate-alignment/SKILL.md +0 -3
- package/templates/awa/.qwen/commands/awa-validate-alignment.md +0 -3
- package/templates/awa/.qwen/skills/awa-validate-alignment/SKILL.md +0 -3
- package/templates/awa/.roo/skills/awa-validate-alignment/SKILL.md +0 -3
- package/templates/awa/.windsurf/skills/awa-validate-alignment/SKILL.md +0 -3
- 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
|
+
[](https://www.npmjs.com/package/awa-cli)
|
|
74
|
+
[](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
|
|
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.
|
|
12
|
+
<read path=".awa/.agent/schemas/*.schema.yaml" required="before writing corresponding file type" />
|
|
13
13
|
</tool>
|
|
14
14
|
<% } %>
|