@pixelfactoryio/theway 0.0.0-stage → 0.4.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/LICENSE +21 -0
- package/README.md +36 -2
- package/dist/theway.js +2674 -0
- package/package.json +33 -4
- package/plugin/.claude-plugin/plugin.json +9 -0
- package/plugin/commands/archive.md +89 -0
- package/plugin/commands/develop-workflow.md +106 -0
- package/plugin/commands/develop.md +38 -0
- package/plugin/commands/document.md +58 -0
- package/plugin/commands/engineering.md +84 -0
- package/plugin/commands/list.md +24 -0
- package/plugin/commands/setup.md +25 -0
- package/plugin/templates/theway/AGENTS.md +170 -0
- package/plugin/templates/theway/CLAUDE.md +17 -0
- package/plugin/templates/theway/changes/archive/.gitkeep +0 -0
- package/plugin/templates/theway/config.yaml +90 -0
- package/plugin/templates/theway/data/standards/architecture-principles.md +50 -0
- package/plugin/templates/theway/data/standards/develop.md +28 -0
- package/plugin/templates/theway/data/standards/interaction.md +13 -0
- package/plugin/templates/theway/data/standards/tamm-framework.md +82 -0
- package/plugin/templates/theway/project.md +31 -0
- package/plugin/templates/theway/templates/coding-standards-template.md +102 -0
- package/plugin/templates/theway/templates/source-tree-template.md +129 -0
- package/plugin/templates/theway/templates/spec-template.md +114 -0
- package/plugin/templates/theway/templates/tasks-template.md +86 -0
- package/plugin/templates/theway/templates/tech-stack-template.md +159 -0
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
<!-- THEWAY:START -->
|
|
2
|
+
# TheWay Instructions
|
|
3
|
+
|
|
4
|
+
> TheWay files are stored in `<home>/<project>/`, where `<home>` is the folder `theway path` prints and `<project>` is your project directory name.
|
|
5
|
+
|
|
6
|
+
Use TheWay slash commands for structured workflows:
|
|
7
|
+
- `/theway:engineering` - Scaffold spec analysis and implementation plan
|
|
8
|
+
- `/theway:document` - Create architecture documentation
|
|
9
|
+
- `/theway:develop` - Implement tasks from a change folder
|
|
10
|
+
- `/theway:develop-workflow` - Develop changes via orchestrated agents (PRs, adversarial review, CI green)
|
|
11
|
+
- `/theway:archive` - Archive completed changes
|
|
12
|
+
- `/theway:list` - List active and archived changes
|
|
13
|
+
|
|
14
|
+
Install with `npx --yes github:pixelfactoryio/theway install` (or `/theway:setup` from a session where theway is loaded).
|
|
15
|
+
|
|
16
|
+
`theway` subcommands (on `PATH`): `list`, `archive`, `path [<project> [<change-id>]] [--verbose]` (prints the theway home, a project folder or a change folder; `--verbose` names where the home came from) and `validate-id <id> [--series]` (change ID format check from `/theway:engineering` Step 2: exit 0 when valid, exit 1 with one reason on stderr).
|
|
17
|
+
<!-- THEWAY:END -->
|
|
File without changes
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# theway configuration
|
|
2
|
+
# <home> is the theway home, the folder `theway path` prints
|
|
3
|
+
|
|
4
|
+
# Standards read by the commands; only `architecture` honors `enabled`
|
|
5
|
+
standards:
|
|
6
|
+
interaction:
|
|
7
|
+
enabled: true
|
|
8
|
+
file: "<home>/data/standards/interaction.md"
|
|
9
|
+
description: "Cross-cutting interaction conventions (exploration, reporting) for all commands"
|
|
10
|
+
|
|
11
|
+
develop:
|
|
12
|
+
enabled: true
|
|
13
|
+
file: "<home>/data/standards/develop.md"
|
|
14
|
+
description: "How a change is implemented and verified, shared by /theway:develop and /theway:develop-workflow"
|
|
15
|
+
|
|
16
|
+
architecture:
|
|
17
|
+
enabled: true
|
|
18
|
+
file: "<home>/data/standards/architecture-principles.md"
|
|
19
|
+
description: "SRE-EE architecture principles and web development standards"
|
|
20
|
+
|
|
21
|
+
tamm_framework:
|
|
22
|
+
enabled: true
|
|
23
|
+
file: "<home>/data/standards/tamm-framework.md"
|
|
24
|
+
description: "Time/Autonomy/Mastery/Machine hardpoint analysis framework"
|
|
25
|
+
|
|
26
|
+
# Change Management Conventions
|
|
27
|
+
changes:
|
|
28
|
+
naming_convention: "[verb]-[description]"
|
|
29
|
+
# Dependent change series: zero-padded two-digit ordinals starting at 01
|
|
30
|
+
series_convention: "[change-id]-NN"
|
|
31
|
+
allowed_verbs:
|
|
32
|
+
- add
|
|
33
|
+
- update
|
|
34
|
+
- refactor
|
|
35
|
+
- remove
|
|
36
|
+
archive_format: "YYYY-MM-DD-[change-id]"
|
|
37
|
+
|
|
38
|
+
# Required files in every change folder
|
|
39
|
+
required_files:
|
|
40
|
+
- spec.md
|
|
41
|
+
- tasks.md
|
|
42
|
+
|
|
43
|
+
# Optional files (create when needed)
|
|
44
|
+
optional_files:
|
|
45
|
+
- design.md
|
|
46
|
+
|
|
47
|
+
# Develop Workflow - caps for /theway:develop-workflow (absent or invalid key means the default)
|
|
48
|
+
workflow:
|
|
49
|
+
# Review rounds per change; 0 skips review and the fix check
|
|
50
|
+
review_rounds: 1
|
|
51
|
+
# CI attempts per change to reach green, re-runs included
|
|
52
|
+
ci_attempts: 2
|
|
53
|
+
# Model per agent role: opus or sonnet (absent or invalid means the default)
|
|
54
|
+
# Lower cost: implementer, fix and ci on sonnet, reviewer on opus
|
|
55
|
+
models:
|
|
56
|
+
implementer: opus
|
|
57
|
+
# Adversarial reviewers and the fix check
|
|
58
|
+
reviewer: opus
|
|
59
|
+
fix: opus
|
|
60
|
+
# CI polling and log fetching
|
|
61
|
+
ci: sonnet
|
|
62
|
+
|
|
63
|
+
# Template Registry
|
|
64
|
+
# Templates are self-contained with frontmatter containing usage instructions,
|
|
65
|
+
# agent roles, required context, and quality standards
|
|
66
|
+
templates:
|
|
67
|
+
value_engineering:
|
|
68
|
+
file: "<home>/templates/spec-template.md"
|
|
69
|
+
description: "TAMM-based Spec analysis for medium-to-large changes"
|
|
70
|
+
used_by: ["engineering"]
|
|
71
|
+
|
|
72
|
+
implementation_tasks:
|
|
73
|
+
file: "<home>/templates/tasks-template.md"
|
|
74
|
+
description: "Phase-based implementation checklist with numbered tasks"
|
|
75
|
+
used_by: ["engineering"]
|
|
76
|
+
|
|
77
|
+
coding_standards:
|
|
78
|
+
file: "<home>/templates/coding-standards-template.md"
|
|
79
|
+
description: "Project-specific coding conventions and quality standards"
|
|
80
|
+
used_by: ["document"]
|
|
81
|
+
|
|
82
|
+
source_tree:
|
|
83
|
+
file: "<home>/templates/source-tree-template.md"
|
|
84
|
+
description: "Repository structure and organization documentation"
|
|
85
|
+
used_by: ["document"]
|
|
86
|
+
|
|
87
|
+
tech_stack:
|
|
88
|
+
file: "<home>/templates/tech-stack-template.md"
|
|
89
|
+
description: "Technology choices, dependencies, and rationale"
|
|
90
|
+
used_by: ["document"]
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# SRE-EE Architecture Principles
|
|
2
|
+
|
|
3
|
+
## Core Principles
|
|
4
|
+
|
|
5
|
+
**Operational Excellence:**
|
|
6
|
+
- Reliability First - Design stable, resilient systems
|
|
7
|
+
- Observability - Make systems transparent and measurable
|
|
8
|
+
- Maintainability - Build systems easy to change and evolve
|
|
9
|
+
- Self-Service - Enable team independence
|
|
10
|
+
- Automation - Reduce manual intervention
|
|
11
|
+
|
|
12
|
+
**Architecture Philosophy:**
|
|
13
|
+
- Progressive Complexity - Start simple, scale when needed
|
|
14
|
+
- Security at Every Layer - Defense in depth
|
|
15
|
+
- User Experience Drives Architecture - Start with journeys, work backward
|
|
16
|
+
- Pragmatic Technology - Boring tech where possible, exciting when necessary
|
|
17
|
+
- Cost-Conscious Engineering - Balance ideals with reality
|
|
18
|
+
- Data-Centric Design - Let data requirements drive architecture
|
|
19
|
+
|
|
20
|
+
## Web Development Standards
|
|
21
|
+
|
|
22
|
+
**Frontend:**
|
|
23
|
+
- Component-based architecture
|
|
24
|
+
- Desktop-first for internal tools
|
|
25
|
+
- Performance: <2s initial load, <500ms navigation
|
|
26
|
+
- Low cognitive load, consistent patterns
|
|
27
|
+
|
|
28
|
+
**API Design:**
|
|
29
|
+
- Resource-based URLs: `/api/v1/services/{id}`
|
|
30
|
+
- Correct HTTP verbs: GET (read), POST (create), PUT (update), DELETE (remove)
|
|
31
|
+
- Consistent response formats
|
|
32
|
+
- OpenAPI/Swagger documentation
|
|
33
|
+
|
|
34
|
+
**Backend:**
|
|
35
|
+
- Single Responsibility - One clear purpose per service
|
|
36
|
+
- Loose Coupling - Minimize service dependencies
|
|
37
|
+
- Stateless Where Possible - Simplify scaling
|
|
38
|
+
- Infrastructure as Code - Version all infrastructure
|
|
39
|
+
|
|
40
|
+
## Quality Standards
|
|
41
|
+
|
|
42
|
+
**Testing:** Unit tests, integration tests, end-to-end tests, load tests
|
|
43
|
+
**Deployment:** CI/CD, feature flags, rollback plans
|
|
44
|
+
**Monitoring:** Structured logs, metrics, tracing, actionable alerts
|
|
45
|
+
**Security:** Authentication, authorization, encryption, input validation, least privilege
|
|
46
|
+
**Performance Targets:** API <200ms (p95), pages <2s initial/<500ms nav, DB <100ms (p95)
|
|
47
|
+
|
|
48
|
+
## References
|
|
49
|
+
|
|
50
|
+
Apply principles pragmatically based on project context. Update as practices evolve.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# TheWay Development Core
|
|
2
|
+
|
|
3
|
+
How a change is implemented, whoever implements it: `/theway:develop` follows this inline, `/theway:develop-workflow` gives it to its implementer agents.
|
|
4
|
+
|
|
5
|
+
## The spec is the contract
|
|
6
|
+
|
|
7
|
+
`spec.md` says what the change must do and why; `tasks.md` breaks it into work; `design.md`, when present, fixes contracts and data. Implement what they describe. The spec was written to be implemented without guessing, so a gap between it and the code is information, not something to smooth over.
|
|
8
|
+
|
|
9
|
+
## Stay inside this change
|
|
10
|
+
|
|
11
|
+
Read only this change's folder (`<change-dir>`, the `changes/<change-id>/` folder that `theway path <project> <change-id>` prints). Do not open other change folders or `changes/archive/`: their tasks belong to other changes, and acting on them would put work in this change that its spec does not ask for. If you need something about the system, read the code and the project's docs.
|
|
12
|
+
|
|
13
|
+
Write only under `<change-dir>` too: never in other change folders or `changes/archive/`.
|
|
14
|
+
|
|
15
|
+
## Implement
|
|
16
|
+
|
|
17
|
+
- Work through the numbered tasks of `tasks.md`. Keep their order unless the spec shows a task does not depend on the ones before it: later tasks usually build on earlier ones.
|
|
18
|
+
- Follow the codebase's existing patterns and `docs/architecture/coding-standards.md` when it exists.
|
|
19
|
+
- Write the tests with the code they cover.
|
|
20
|
+
- Tick each task (`- [x] N.`) once it is done, and record anything you learn that the next person needs in the Notes section of `tasks.md`.
|
|
21
|
+
|
|
22
|
+
## When the spec does not fit
|
|
23
|
+
|
|
24
|
+
If the code contradicts the spec, a task cannot be done as written, or doing it well needs a decision the spec does not make, stop and bring it back: what you found, and the options you see. Carrying on with your own fix would leave a spec that no longer describes the code, and the decision would be made without the person who owns the change. Once it is decided, update `spec.md` (the decision and why) and `tasks.md`, then continue. A risk the spec did not foresee goes into its Hardpoints table.
|
|
25
|
+
|
|
26
|
+
## Verify
|
|
27
|
+
|
|
28
|
+
Done means the change does what the spec says, not that every task is ticked. Run the project's tests and build, and the commands the project's CI runs (read them from its CI configuration) where they can run locally; report the ones that cannot run locally. Then check each Success Criterion of `spec.md` and note how you verified it: the command and its result, or the test that covers it. A criterion you could not verify is reported as such.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# TheWay Interaction Conventions
|
|
2
|
+
|
|
3
|
+
Cross-cutting behavior for all TheWay commands. Load and apply these in every mode.
|
|
4
|
+
|
|
5
|
+
## Exploration
|
|
6
|
+
|
|
7
|
+
- Explore the codebase with the `Glob`, `Grep`, and `Read` tools. Do not shell out to Bash (`find`, `ls`, `grep`, `cat`) for discovery or reading — the file tools are exact replacements.
|
|
8
|
+
- Read-only Bash the file tools can't cover (`git log`, `git diff`, `wc`, `tree`, `stat`) is fine.
|
|
9
|
+
|
|
10
|
+
## Reporting
|
|
11
|
+
|
|
12
|
+
- Never narrate TheWay mode or which command to run next (e.g. "staying read-only", "no repo files touched", "run /theway:develop to implement"). Staying in the current mode is the default, not news.
|
|
13
|
+
- Report only spec/tasks/implementation progress and what is actionable.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# TAMM Framework
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
The **Time/Autonomy/Mastery/Machine (TAMM)** framework identifies potential obstacles in technical implementations during Spec analysis.
|
|
6
|
+
|
|
7
|
+
## Quick Reference
|
|
8
|
+
|
|
9
|
+
**Time Hardpoints:**
|
|
10
|
+
- Timeline pressures, compressed schedules, external deadlines
|
|
11
|
+
- Dependencies and blocking, critical path bottlenecks
|
|
12
|
+
- Resource contention, competing priorities
|
|
13
|
+
- Countermeasures: Timeline buffering, parallel work, resource reallocation
|
|
14
|
+
|
|
15
|
+
**Autonomy Hardpoints:**
|
|
16
|
+
- Decision-making constraints, approval bottlenecks
|
|
17
|
+
- Organizational dependencies, policy constraints
|
|
18
|
+
- Communication barriers, stakeholder alignment
|
|
19
|
+
- Countermeasures: Pre-approval, delegation, streamlined processes
|
|
20
|
+
|
|
21
|
+
**Mastery Hardpoints:**
|
|
22
|
+
- Skill gaps, technology unfamiliarity, domain expertise
|
|
23
|
+
- Learning curves, complex systems, best practices
|
|
24
|
+
- Knowledge transfer, documentation gaps, key person dependencies
|
|
25
|
+
- Countermeasures: Training, pair programming, expert consultation
|
|
26
|
+
|
|
27
|
+
**Machine Hardpoints:**
|
|
28
|
+
- Performance constraints, scalability limits, latency requirements
|
|
29
|
+
- Infrastructure limitations, legacy systems, security constraints
|
|
30
|
+
- Integration challenges, API limitations, protocol mismatches
|
|
31
|
+
- Technical debt, code quality issues, architecture limitations
|
|
32
|
+
- Countermeasures: Infrastructure upgrades, optimization, refactoring
|
|
33
|
+
|
|
34
|
+
## Analysis Questions
|
|
35
|
+
|
|
36
|
+
**Time Questions:**
|
|
37
|
+
- "What could cause delays in this timeline?"
|
|
38
|
+
- "Where are the critical path bottlenecks?"
|
|
39
|
+
- "What external factors could impact timing?"
|
|
40
|
+
|
|
41
|
+
**Autonomy Questions:**
|
|
42
|
+
- "Who needs to approve this decision?"
|
|
43
|
+
- "What organizational constraints exist?"
|
|
44
|
+
- "Where might we get blocked by process?"
|
|
45
|
+
|
|
46
|
+
**Mastery Questions:**
|
|
47
|
+
- "What skills are required that we don't have?"
|
|
48
|
+
- "What knowledge gaps exist?"
|
|
49
|
+
- "Where might we struggle technically?"
|
|
50
|
+
|
|
51
|
+
**Machine Questions:**
|
|
52
|
+
- "What are the system limitations?"
|
|
53
|
+
- "Where might performance be an issue?"
|
|
54
|
+
- "What technical constraints exist?"
|
|
55
|
+
|
|
56
|
+
## Compound Hardpoints
|
|
57
|
+
|
|
58
|
+
Some challenges span multiple dimensions:
|
|
59
|
+
|
|
60
|
+
**Time + Mastery:** Learning while delivering, training overhead
|
|
61
|
+
**Autonomy + Machine:** Architecture decisions needing approval, infrastructure access requiring permission
|
|
62
|
+
**Time + Autonomy + Mastery:** External expertise coordination, knowledge transfer timing
|
|
63
|
+
|
|
64
|
+
## Risk Level Guidelines
|
|
65
|
+
|
|
66
|
+
**Low Risk:** Clear countermeasures available, team has experience, no blockers expected
|
|
67
|
+
**Medium Risk:** Some uncertainty, team has limited experience, potential blockers but manageable
|
|
68
|
+
**High Risk:** Unclear countermeasures, team lacks experience, likely blockers or critical dependencies
|
|
69
|
+
|
|
70
|
+
## Common Pitfalls
|
|
71
|
+
|
|
72
|
+
- **Optimism Bias** - Underestimating challenge severity
|
|
73
|
+
- **Single Dimension Focus** - Missing cross-dimensional issues
|
|
74
|
+
- **Generic Solutions** - Applying standard fixes without context
|
|
75
|
+
- **Analysis Paralysis** - Over-analyzing without moving to action
|
|
76
|
+
|
|
77
|
+
## Validation Methods
|
|
78
|
+
|
|
79
|
+
- **Pre-mortem Analysis** - Imagine the project failed, why?
|
|
80
|
+
- **Stakeholder Interviews** - Get perspectives from different roles
|
|
81
|
+
- **Historical Analysis** - Review similar past projects
|
|
82
|
+
- **Expert Review** - Get input from experienced team members
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Project Context
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
[Describe your project's purpose and goals]
|
|
5
|
+
|
|
6
|
+
## Tech Stack
|
|
7
|
+
- [List your primary technologies]
|
|
8
|
+
- [e.g., TypeScript, React, Node.js, Python, Go]
|
|
9
|
+
|
|
10
|
+
## Project Conventions
|
|
11
|
+
|
|
12
|
+
### Code Style
|
|
13
|
+
[Describe code style preferences, formatting rules, naming conventions]
|
|
14
|
+
|
|
15
|
+
### Architecture Patterns
|
|
16
|
+
[Document architectural decisions and patterns]
|
|
17
|
+
|
|
18
|
+
### Testing Strategy
|
|
19
|
+
[Explain testing approach and requirements]
|
|
20
|
+
|
|
21
|
+
### Git Workflow
|
|
22
|
+
[Describe branching strategy and commit conventions]
|
|
23
|
+
|
|
24
|
+
## Domain Context
|
|
25
|
+
[Add domain-specific knowledge AI assistants need to understand]
|
|
26
|
+
|
|
27
|
+
## Important Constraints
|
|
28
|
+
[List technical, business, or regulatory constraints]
|
|
29
|
+
|
|
30
|
+
## External Dependencies
|
|
31
|
+
[Document key external services, APIs, or systems]
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
---
|
|
2
|
+
template_type: "coding_standards"
|
|
3
|
+
usage: "Document project-specific coding conventions when using /theway:document to fill documentation gaps"
|
|
4
|
+
agent_role: "System Architect documenting coding standards following SRE-EE operational excellence principles"
|
|
5
|
+
required_context:
|
|
6
|
+
- "<home>/config.yaml - Global config and conventions"
|
|
7
|
+
- "<home>/data/standards/architecture-principles.md - SRE-EE principles (if enabled)"
|
|
8
|
+
- "Existing codebase - Review actual patterns and conventions in use"
|
|
9
|
+
quality_standards:
|
|
10
|
+
- "Conventions reflect actual codebase patterns (not aspirational)"
|
|
11
|
+
- "Naming conventions table is complete with examples"
|
|
12
|
+
- "Critical rules prevent common mistakes in this codebase"
|
|
13
|
+
- "Error handling patterns match existing code"
|
|
14
|
+
- "Testing requirements are realistic and achievable"
|
|
15
|
+
- "Review checklist is actionable for code reviews"
|
|
16
|
+
- "Language-specific guidelines address real project needs"
|
|
17
|
+
workflow_steps:
|
|
18
|
+
- "1. Review existing codebase to identify current patterns"
|
|
19
|
+
- "2. Document languages, runtimes, and linting tools in use"
|
|
20
|
+
- "3. Create naming conventions table from actual code examples"
|
|
21
|
+
- "4. List critical rules that prevent project-specific mistakes"
|
|
22
|
+
- "5. Document error handling and testing patterns from codebase"
|
|
23
|
+
- "6. Create practical review checklist"
|
|
24
|
+
best_practices:
|
|
25
|
+
- "Document what IS done, not what SHOULD be done"
|
|
26
|
+
- "Provide real examples from the codebase"
|
|
27
|
+
- "Focus on standards that prevent actual bugs"
|
|
28
|
+
- "Keep critical rules list focused (5-10 items max)"
|
|
29
|
+
- "Make review checklist practical for daily use"
|
|
30
|
+
- "Update as conventions evolve"
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
# Coding Standards
|
|
34
|
+
|
|
35
|
+
## Overview
|
|
36
|
+
|
|
37
|
+
Project-specific coding conventions and quality standards for {{PROJECT_NAME}}.
|
|
38
|
+
|
|
39
|
+
## Languages & Runtimes
|
|
40
|
+
|
|
41
|
+
- **Primary Language:** {{LANGUAGE}} {{VERSION}}
|
|
42
|
+
- **Runtime:** {{RUNTIME}}
|
|
43
|
+
- **Style & Linting:** {{LINTER_CONFIG}}
|
|
44
|
+
|
|
45
|
+
## Naming Conventions
|
|
46
|
+
|
|
47
|
+
| Element | Convention | Example |
|
|
48
|
+
|---------|------------|---------|
|
|
49
|
+
| Files | {{FILE_CONVENTION}} | {{FILE_EXAMPLE}} |
|
|
50
|
+
| Functions | {{FUNCTION_CONVENTION}} | {{FUNCTION_EXAMPLE}} |
|
|
51
|
+
| Variables | {{VARIABLE_CONVENTION}} | {{VARIABLE_EXAMPLE}} |
|
|
52
|
+
| Constants | {{CONSTANT_CONVENTION}} | {{CONSTANT_EXAMPLE}} |
|
|
53
|
+
|
|
54
|
+
## Code Organization
|
|
55
|
+
|
|
56
|
+
- **Module Structure:** {{MODULE_STRUCTURE}}
|
|
57
|
+
- **File Organization:** {{FILE_ORGANIZATION}}
|
|
58
|
+
- **Import Order:** {{IMPORT_ORDER}}
|
|
59
|
+
|
|
60
|
+
## Critical Rules
|
|
61
|
+
|
|
62
|
+
List project-specific rules that prevent common mistakes or enforce architectural patterns:
|
|
63
|
+
|
|
64
|
+
- **{{RULE_NAME}}:** {{RULE_DESCRIPTION}}
|
|
65
|
+
- **{{RULE_NAME}}:** {{RULE_DESCRIPTION}}
|
|
66
|
+
- **{{RULE_NAME}}:** {{RULE_DESCRIPTION}}
|
|
67
|
+
|
|
68
|
+
## Error Handling
|
|
69
|
+
|
|
70
|
+
- **Pattern:** {{ERROR_PATTERN}}
|
|
71
|
+
- **Logging:** {{LOGGING_STANDARD}}
|
|
72
|
+
- **Error Types:** {{ERROR_TYPES}}
|
|
73
|
+
|
|
74
|
+
## Testing Requirements
|
|
75
|
+
|
|
76
|
+
- **Test Location:** {{TEST_LOCATION}}
|
|
77
|
+
- **Naming Convention:** {{TEST_NAMING}}
|
|
78
|
+
- **Coverage Target:** {{COVERAGE_TARGET}}
|
|
79
|
+
- **Test Organization:** {{TEST_ORGANIZATION}}
|
|
80
|
+
|
|
81
|
+
## Review Checklist
|
|
82
|
+
|
|
83
|
+
Before submitting code for review:
|
|
84
|
+
|
|
85
|
+
- [ ] Code follows naming conventions
|
|
86
|
+
- [ ] All critical rules are satisfied
|
|
87
|
+
- [ ] Error handling is consistent
|
|
88
|
+
- [ ] Tests are written and passing
|
|
89
|
+
- [ ] Code is properly documented
|
|
90
|
+
- [ ] No security vulnerabilities introduced
|
|
91
|
+
- [ ] Performance considerations addressed
|
|
92
|
+
|
|
93
|
+
## Language-Specific Guidelines
|
|
94
|
+
|
|
95
|
+
### {{LANGUAGE_NAME}}
|
|
96
|
+
|
|
97
|
+
- **{{GUIDELINE_TOPIC}}:** {{GUIDELINE_DETAIL}}
|
|
98
|
+
- **{{GUIDELINE_TOPIC}}:** {{GUIDELINE_DETAIL}}
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
**Last Updated:** {{DATE}}
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
template_type: "source_tree"
|
|
3
|
+
usage: "Document repository structure and organization when using /theway:document to fill documentation gaps"
|
|
4
|
+
agent_role: "System Architect documenting codebase structure for team onboarding and navigation"
|
|
5
|
+
required_context:
|
|
6
|
+
- "<home>/config.yaml - Global config and conventions"
|
|
7
|
+
- "Repository root - Review actual directory structure"
|
|
8
|
+
- "Build configuration files - Understand build artifacts"
|
|
9
|
+
quality_standards:
|
|
10
|
+
- "ASCII tree accurately reflects actual repository structure"
|
|
11
|
+
- "Directory purposes clearly explain each folder's role"
|
|
12
|
+
- "Key files are documented with their specific purposes"
|
|
13
|
+
- "Module organization shows relationships between components"
|
|
14
|
+
- "Finding Functionality section helps locate features quickly"
|
|
15
|
+
- "Component relationships diagram shows data/control flow"
|
|
16
|
+
- "Build artifacts locations are accurate"
|
|
17
|
+
workflow_steps:
|
|
18
|
+
- "1. Generate repository tree structure (use ls or tree command)"
|
|
19
|
+
- "2. Document purpose of each major directory"
|
|
20
|
+
- "3. Identify and list key files with their roles"
|
|
21
|
+
- "4. Map module organization and dependencies"
|
|
22
|
+
- "5. Create finding functionality guide for common features"
|
|
23
|
+
- "6. Document build output and artifact locations"
|
|
24
|
+
best_practices:
|
|
25
|
+
- "Use actual directory structure, not idealized version"
|
|
26
|
+
- "Explain WHY directories exist, not just WHAT they contain"
|
|
27
|
+
- "Include examples of where to find specific functionality"
|
|
28
|
+
- "Update when directory structure changes significantly"
|
|
29
|
+
- "Keep descriptions concise but informative"
|
|
30
|
+
- "Add mermaid diagram for complex component relationships"
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
# Source Tree
|
|
34
|
+
|
|
35
|
+
## Overview
|
|
36
|
+
|
|
37
|
+
Source code organization and structure for {{PROJECT_NAME}}.
|
|
38
|
+
|
|
39
|
+
## Repository Structure
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
{{PROJECT_ROOT}}/
|
|
43
|
+
├── {{DIR_1}}/ # {{DIR_1_PURPOSE}}
|
|
44
|
+
│ ├── {{SUBDIR_1}}/ # {{SUBDIR_1_PURPOSE}}
|
|
45
|
+
│ └── {{SUBDIR_2}}/ # {{SUBDIR_2_PURPOSE}}
|
|
46
|
+
├── {{DIR_2}}/ # {{DIR_2_PURPOSE}}
|
|
47
|
+
├── {{DIR_3}}/ # {{DIR_3_PURPOSE}}
|
|
48
|
+
└── {{CONFIG_FILE}} # {{CONFIG_FILE_PURPOSE}}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Directory Purposes
|
|
52
|
+
|
|
53
|
+
### {{DIR_1}}/
|
|
54
|
+
{{DIR_1_DESCRIPTION}}
|
|
55
|
+
|
|
56
|
+
**Key Files:**
|
|
57
|
+
- `{{FILE_1}}` - {{FILE_1_PURPOSE}}
|
|
58
|
+
- `{{FILE_2}}` - {{FILE_2_PURPOSE}}
|
|
59
|
+
|
|
60
|
+
### {{DIR_2}}/
|
|
61
|
+
{{DIR_2_DESCRIPTION}}
|
|
62
|
+
|
|
63
|
+
**Key Files:**
|
|
64
|
+
- `{{FILE_1}}` - {{FILE_1_PURPOSE}}
|
|
65
|
+
- `{{FILE_2}}` - {{FILE_2_PURPOSE}}
|
|
66
|
+
|
|
67
|
+
### {{DIR_3}}/
|
|
68
|
+
{{DIR_3_DESCRIPTION}}
|
|
69
|
+
|
|
70
|
+
**Key Files:**
|
|
71
|
+
- `{{FILE_1}}` - {{FILE_1_PURPOSE}}
|
|
72
|
+
- `{{FILE_2}}` - {{FILE_2_PURPOSE}}
|
|
73
|
+
|
|
74
|
+
## Module Organization
|
|
75
|
+
|
|
76
|
+
{{MODULE_ORGANIZATION_DESCRIPTION}}
|
|
77
|
+
|
|
78
|
+
### {{MODULE_1}}
|
|
79
|
+
- **Location:** `{{MODULE_1_PATH}}`
|
|
80
|
+
- **Purpose:** {{MODULE_1_PURPOSE}}
|
|
81
|
+
- **Dependencies:** {{MODULE_1_DEPS}}
|
|
82
|
+
|
|
83
|
+
### {{MODULE_2}}
|
|
84
|
+
- **Location:** `{{MODULE_2_PATH}}`
|
|
85
|
+
- **Purpose:** {{MODULE_2_PURPOSE}}
|
|
86
|
+
- **Dependencies:** {{MODULE_2_DEPS}}
|
|
87
|
+
|
|
88
|
+
## File Naming Conventions
|
|
89
|
+
|
|
90
|
+
- **Source Files:** {{SOURCE_FILE_CONVENTION}}
|
|
91
|
+
- **Test Files:** {{TEST_FILE_CONVENTION}}
|
|
92
|
+
- **Configuration Files:** {{CONFIG_FILE_CONVENTION}}
|
|
93
|
+
- **Documentation Files:** {{DOC_FILE_CONVENTION}}
|
|
94
|
+
|
|
95
|
+
## Component Relationships
|
|
96
|
+
|
|
97
|
+
```mermaid
|
|
98
|
+
graph TD
|
|
99
|
+
A[{{COMPONENT_1}}] --> B[{{COMPONENT_2}}]
|
|
100
|
+
A --> C[{{COMPONENT_3}}]
|
|
101
|
+
B --> D[{{COMPONENT_4}}]
|
|
102
|
+
C --> D
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
{{COMPONENT_RELATIONSHIPS_DESCRIPTION}}
|
|
106
|
+
|
|
107
|
+
## Finding Functionality
|
|
108
|
+
|
|
109
|
+
### {{FEATURE_1}}
|
|
110
|
+
**Location:** `{{FEATURE_1_PATH}}`
|
|
111
|
+
**Key Files:** {{FEATURE_1_FILES}}
|
|
112
|
+
|
|
113
|
+
### {{FEATURE_2}}
|
|
114
|
+
**Location:** `{{FEATURE_2_PATH}}`
|
|
115
|
+
**Key Files:** {{FEATURE_2_FILES}}
|
|
116
|
+
|
|
117
|
+
### {{FEATURE_3}}
|
|
118
|
+
**Location:** `{{FEATURE_3_PATH}}`
|
|
119
|
+
**Key Files:** {{FEATURE_3_FILES}}
|
|
120
|
+
|
|
121
|
+
## Build Artifacts
|
|
122
|
+
|
|
123
|
+
- **Build Output:** `{{BUILD_OUTPUT_DIR}}/`
|
|
124
|
+
- **Test Output:** `{{TEST_OUTPUT_DIR}}/`
|
|
125
|
+
- **Distribution:** `{{DIST_DIR}}/`
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
**Last Updated:** {{DATE}}
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
template_type: "value_engineering"
|
|
3
|
+
usage: "Create Spec analysis when planning medium-to-large changes requiring TAMM hardpoint analysis"
|
|
4
|
+
agent_role: "Spec Analyst who analyzes solutions using the TAMM framework (Time/Autonomy/Mastery/Machine)"
|
|
5
|
+
required_context:
|
|
6
|
+
- "<home>/config.yaml - Global config and conventions"
|
|
7
|
+
- "<home>/data/standards/tamm-framework.md - TAMM framework"
|
|
8
|
+
- "<home>/data/standards/architecture-principles.md - SRE-EE principles (if enabled)"
|
|
9
|
+
- "docs/architecture/coding-standards.md - Project coding standards (if exists)"
|
|
10
|
+
quality_standards:
|
|
11
|
+
- "TAMM table includes only Medium/High risk hardpoints (skip low-risk items)"
|
|
12
|
+
- "Technical decisions have clear rationale explaining trade-offs"
|
|
13
|
+
- "Scope clearly defines in-scope and out-of-scope boundaries"
|
|
14
|
+
- "Implementation phases align with tasks.md structure"
|
|
15
|
+
- "Countermeasures are specific and actionable (not generic)"
|
|
16
|
+
- "Success criteria are measurable with checkboxes"
|
|
17
|
+
workflow_steps:
|
|
18
|
+
- "1. Understand the problem and proposed solution clearly"
|
|
19
|
+
- "2. Identify key components and technical decisions"
|
|
20
|
+
- "3. Analyze each TAMM dimension for Medium/High risks only"
|
|
21
|
+
- "4. Define clear scope boundaries (in/out of scope)"
|
|
22
|
+
- "5. Break implementation into logical phases with milestones"
|
|
23
|
+
- "6. Create measurable success criteria"
|
|
24
|
+
best_practices:
|
|
25
|
+
- "Challenge assumptions: 'What would we need for this to work?'"
|
|
26
|
+
- "Ensure complete solution coverage: frontend, backend, API, migrations, monitoring"
|
|
27
|
+
- "Consider edge cases, error scenarios, and operational concerns"
|
|
28
|
+
- "Focus on medium/high-risk hardpoints only - skip low-risk items"
|
|
29
|
+
- "Keep analysis practical and actionable, not verbose"
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
# Spec Analysis: [Change Name]
|
|
33
|
+
|
|
34
|
+
## Solution
|
|
35
|
+
|
|
36
|
+
**Problem:** [1-2 sentence problem statement]
|
|
37
|
+
|
|
38
|
+
**Proposed Solution:**
|
|
39
|
+
|
|
40
|
+
[2-3 paragraphs describing the technical solution. Focus on what you're building/changing and how it addresses the problem.]
|
|
41
|
+
|
|
42
|
+
**Key Components:**
|
|
43
|
+
- **[Component 1]:** Brief description
|
|
44
|
+
- **[Component 2]:** Brief description
|
|
45
|
+
- **[Component 3]:** Brief description
|
|
46
|
+
|
|
47
|
+
## Technical Approach
|
|
48
|
+
|
|
49
|
+
**Technical Decisions:**
|
|
50
|
+
- **[Decision 1]:** [Rationale]
|
|
51
|
+
- **[Decision 2]:** [Rationale]
|
|
52
|
+
- **[Decision 3]:** [Rationale]
|
|
53
|
+
|
|
54
|
+
**Architecture Changes:**
|
|
55
|
+
[Describe any architectural changes or patterns being introduced]
|
|
56
|
+
|
|
57
|
+
**Data Model Changes:**
|
|
58
|
+
[Describe any database schema, data structure, or storage changes. Omit if none.]
|
|
59
|
+
|
|
60
|
+
**API Changes:**
|
|
61
|
+
[Describe any API changes, new endpoints, or contract modifications. Omit if none.]
|
|
62
|
+
|
|
63
|
+
## Scope
|
|
64
|
+
|
|
65
|
+
**In Scope:**
|
|
66
|
+
- [What will be included]
|
|
67
|
+
- [What will be addressed]
|
|
68
|
+
- [What will be built]
|
|
69
|
+
|
|
70
|
+
**Out of Scope:**
|
|
71
|
+
- [What will not be included]
|
|
72
|
+
- [What will be deferred]
|
|
73
|
+
- [What is explicitly excluded]
|
|
74
|
+
|
|
75
|
+
## Hardpoints (TAMM Analysis)
|
|
76
|
+
|
|
77
|
+
**Only document Medium/High risk hardpoints. Omit low-risk items.**
|
|
78
|
+
|
|
79
|
+
| Category | Risk | Impact | Countermeasures |
|
|
80
|
+
|----------|------|--------|-----------------|
|
|
81
|
+
| Time (T) | Med/High | [How this constraint affects delivery timeline] | 1. [Countermeasure]<br>2. [Countermeasure]<br>3. [Countermeasure] |
|
|
82
|
+
| Autonomy (A) | Med/High | [How this constraint affects decision-making] | 1. [Countermeasure]<br>2. [Countermeasure] |
|
|
83
|
+
| Mastery (M) | Med/High | [How this gap affects implementation quality] | 1. [Countermeasure]<br>2. [Countermeasure] |
|
|
84
|
+
| Machine (M) | Med/High | [How this limitation constrains the solution] | 1. [Countermeasure]<br>2. [Countermeasure] |
|
|
85
|
+
|
|
86
|
+
**TAMM Legend:**
|
|
87
|
+
- **Time**: Timeline constraints, dependencies, blocking risks
|
|
88
|
+
- **Autonomy**: Decision authority, organizational constraints, approval needs
|
|
89
|
+
- **Mastery**: Skill gaps, knowledge requirements, learning curves
|
|
90
|
+
- **Machine**: System limitations, performance constraints, infrastructure issues
|
|
91
|
+
|
|
92
|
+
## Implementation
|
|
93
|
+
|
|
94
|
+
**Phases:**
|
|
95
|
+
|
|
96
|
+
**Phase 1: [Phase Name]**
|
|
97
|
+
- [High-level milestone]
|
|
98
|
+
- [High-level milestone]
|
|
99
|
+
|
|
100
|
+
**Phase 2: [Phase Name]**
|
|
101
|
+
- [High-level milestone]
|
|
102
|
+
- [High-level milestone]
|
|
103
|
+
|
|
104
|
+
**Phase 3: [Phase Name]**
|
|
105
|
+
- [High-level milestone]
|
|
106
|
+
- [High-level milestone]
|
|
107
|
+
|
|
108
|
+
**Success Criteria:**
|
|
109
|
+
- [ ] [Criterion 1]
|
|
110
|
+
- [ ] [Criterion 2]
|
|
111
|
+
- [ ] [Criterion 3]
|
|
112
|
+
- [ ] [Criterion 4]
|
|
113
|
+
|
|
114
|
+
**Estimated Effort:** [Duration estimate]
|