Skip to content

Commit d8afa91

Browse files
karaposukaraposu
committed
edit
1 parent b3501be commit d8afa91

10 files changed

Lines changed: 1232 additions & 1 deletion

‎commands/align-modes.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# /align-modes — Multi-Modal Task Assessment
2+
3+
For a given task, assess what is needed across all seven intent modes and all six alignment layers. This produces a complete picture of what the task requires — not just what to build, but what to explore, what to innovate, what might break, what to maintain, and what to reflect on.
4+
5+
## Additional Input/Instructions
6+
7+
$ARGUMENTS
8+
9+
---
10+
11+
## Instructions
12+
13+
### Step 1: Identify the Task
14+
15+
Determine which task to assess:
16+
- If a path is given (e.g., `devdocs/scoped/feat_3_auth/`), read its docs
17+
- If a task description is given, use it directly
18+
- If nothing is given, check recent conversation context
19+
- If still unclear, ask
20+
21+
Read the task's desc.md, plan, critic, and any related docs. Understand what the task is trying to achieve.
22+
23+
### Step 2: Assess Each Mode
24+
25+
For the given task, analyze what is needed across each mode. Read relevant codebase files and devdocs to ground each assessment in reality — do not speculate without checking.
26+
27+
#### Exploration — "What do we need to understand first?"
28+
29+
| Layer | What needs exploring? |
30+
|-------|----------------------|
31+
| Workspace | What codebase areas need reading before starting? What context is missing? |
32+
| Task | What about the task is unclear or ambiguous? What assumptions haven't been validated? |
33+
| Action-Space | What approaches exist for this? What has been tried before in this codebase? |
34+
| Action-Set | What implementation patterns does this codebase use for similar work? |
35+
| Coherence | What existing systems does this task touch? What are their current states? |
36+
| Outcome | What does success look like? Are the criteria measurable and testable? |
37+
38+
#### Alignment — "What needs to be correct?"
39+
40+
| Layer | What alignment is needed? |
41+
|-------|--------------------------|
42+
| Workspace | Is the right context loaded? Are archaeology docs fresh for the relevant areas? |
43+
| Task | Is intent clear? Is scope bounded? Are success criteria specific enough to verify? |
44+
| Action-Space | Are the viable approaches identified and evaluated? Is the chosen approach justified? |
45+
| Action-Set | Does a plan exist? Is it sequenced correctly? Are dependencies explicit? |
46+
| Coherence | What existing features, modules, or contracts must not break? What needs checking after implementation? |
47+
| Outcome | How will we verify the result matches the intent? What tests or probes are needed? |
48+
49+
#### Innovation — "Where might we need novel approaches?"
50+
51+
| Layer | Where might innovation be needed? |
52+
|-------|-----------------------------------|
53+
| Workspace | Does the task require new tooling, environments, or context structures? |
54+
| Task | Is the task framing correct, or might the real problem be different from what's stated? |
55+
| Action-Space | Are existing approaches sufficient, or does this task require something that doesn't exist yet? |
56+
| Action-Set | Can this be built with standard patterns, or does it need novel combinations? |
57+
| Coherence | Does this task require deliberately breaking existing patterns to establish better ones? |
58+
| Outcome | Should the success criteria be redefined? Is the original goal still the right goal? |
59+
60+
#### Diagnostic — "What could go wrong?"
61+
62+
| Layer | What should we watch for? |
63+
|-------|--------------------------|
64+
| Workspace | What context could be stale or misleading? |
65+
| Task | Where is the task description most likely to be misunderstood? |
66+
| Action-Space | What approach pitfalls exist? What has failed before in similar tasks? |
67+
| Action-Set | What plan steps are most likely to fail? Where is the plan weakest? |
68+
| Coherence | What is most likely to break? What are the fragile points in affected modules? |
69+
| Outcome | What's the most likely way the result could look correct but be wrong? |
70+
71+
#### Maintenance — "What needs upkeep?"
72+
73+
| Layer | What maintenance is relevant? |
74+
|-------|------------------------------|
75+
| Workspace | Are archaeology docs fresh for the areas this task touches? |
76+
| Task | Are there stale or superseded task docs that should be archived? |
77+
| Action-Space | Are previous approach evaluations still valid? |
78+
| Action-Set | Do existing plans for related work still match the codebase? |
79+
| Coherence | Has anything drifted since the task was planned? |
80+
| Outcome | Are previous verification results still valid? |
81+
82+
#### Recovery — "What's the fallback?"
83+
84+
| Layer | What recovery options exist? |
85+
|-------|----------------------------|
86+
| Workspace | Can we restore context if something goes wrong? |
87+
| Task | If the task needs re-scoping mid-implementation, what's the rollback point? |
88+
| Action-Space | If the chosen approach fails, what's the next best alternative? |
89+
| Action-Set | If implementation breaks things, what's the minimal revert? |
90+
| Coherence | What's the known-good state we'd restore to? |
91+
| Outcome | If the result doesn't match intent, what's the recovery path? |
92+
93+
#### Reflection — "What should we learn from this?"
94+
95+
| Layer | What's worth reflecting on? |
96+
|-------|---------------------------|
97+
| Workspace | Did the context setup work well? What would make it better next time? |
98+
| Task | Did the task description capture the real need? What was missing? |
99+
| Action-Space | Were the right approaches considered? Did we miss better options? |
100+
| Action-Set | Did the plan hold up during implementation? Where did it deviate? |
101+
| Coherence | Did we anticipate the right risks? What surprised us? |
102+
| Outcome | Did success criteria actually capture what mattered? |
103+
104+
### Step 3: Synthesize
105+
106+
After the per-mode assessment, produce a synthesis:
107+
108+
```markdown
109+
## Synthesis
110+
111+
### Critical items before starting
112+
[What MUST be done before implementation — missing exploration, unresolved alignment gaps, potential innovation needs]
113+
114+
### Highest risk areas
115+
[Where things are most likely to go wrong — from diagnostic assessment]
116+
117+
### Mode sequence recommendation
118+
[Suggested order of modes for this task. E.g., "Exploration first (modules X and Y need reading), then Alignment (plan needs critique), then proceed to implementation. Diagnostic focus on auth middleware during implementation."]
119+
120+
### Maintenance actions
121+
[Any housekeeping needed before or after this task]
122+
123+
### Recovery plan
124+
[If things go wrong, here's the fallback]
125+
```
126+
127+
---
128+
129+
## Rules
130+
131+
1. **Check reality, don't speculate.** Read the actual codebase files and devdocs for each assessment. "This module might be fragile" is weak. "This module has 3 undocumented side effects (from traces)" is useful.
132+
2. **Be concise per cell.** Each mode × layer cell should be 1-3 sentences. The synthesis is where you elaborate.
133+
3. **Skip cells that don't apply.** If innovation is clearly not needed for this task, say "Not applicable — standard approaches are sufficient" and move on. Don't force novelty.
134+
4. **The synthesis is the most valuable part.** The tables are the analysis. The synthesis is the actionable output — what to do, in what order, watching for what.
135+
136+
---
137+
138+
## Output
139+
140+
Full multi-modal assessment printed in conversation. Not saved to file by default — this is a working assessment, not an artifact. The user can save it if they want.

‎commands/align.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# /align — Load Context and Assess Alignment for a Task
2+
3+
Read all relevant context for a task, identify gaps, and prepare to work on it properly. This is the "be a responsible developer" command — load before you build.
4+
5+
## Additional Input/Instructions
6+
7+
$ARGUMENTS
8+
9+
---
10+
11+
## Instructions
12+
13+
### Step 1: Identify the Task
14+
15+
Determine which task to align on:
16+
- If a path is given (e.g., `devdocs/scoped/feat_3_auth/`), use it
17+
- If a task name or description is given, find the matching devdocs folder
18+
- If nothing is given, check recent conversation context for the active task
19+
- If still unclear, list active tasks (folders in `devdocs/scoped/` and `devdocs/ideas/`) and ask which one
20+
21+
### Step 2: Load Workspace Context (Layer 1)
22+
23+
Check and read archaeology:
24+
- Read `devdocs/archaeology/small_summary.md` if it exists — note how old it is
25+
- Read `devdocs/archaeology/intro2codebase.md` if it exists — note how old it is
26+
- Scan `devdocs/archaeology/traces/` — read traces relevant to the task's area
27+
28+
If archaeology is missing or stale (summary > 30 days, intro > 15 days, traces > 7 days), note it as a gap.
29+
30+
Read any other workspace context relevant to the task (related devdocs, roadmaps, recent reports).
31+
32+
### Step 3: Load Task Context (Layer 2)
33+
34+
Read everything in the task's folder:
35+
- `desc.md` — is the task well-defined? Are success criteria present and specific?
36+
- `elaboration.md` or `sensemaking.md` — any exploratory context?
37+
- Any other docs in the folder
38+
39+
Assess: is the task intent clear? Is depth understood? Is scope defined?
40+
41+
### Step 4: Check Action-Space and Action-Set (Layers 3-4)
42+
43+
- `step_by_step_impl_plan.md` — does a plan exist? Is it detailed enough?
44+
- `critic.md` or `dynamic_critic_prompt.md` — was the plan critiqued?
45+
- If critic exists, were the issues addressed? Compare critic findings against the plan — are high-severity items still unresolved?
46+
47+
### Step 5: Assess Coherence Risk (Layer 5)
48+
49+
Based on what the task touches:
50+
- Identify which modules/files the task will modify (from the plan, or infer from desc.md)
51+
- Read those modules — understand their current state
52+
- Check archaeology traces for those modules if available
53+
- Note any known fragile areas, undocumented side effects, or tight coupling
54+
55+
### Step 6: Check Outcome Readiness (Layer 6)
56+
57+
- Are success criteria defined in desc.md?
58+
- Do test scenarios exist?
59+
- Is there a way to verify the task is done correctly?
60+
61+
### Step 7: Report
62+
63+
Print a concise alignment report:
64+
65+
```markdown
66+
## Alignment Report: [task name]
67+
68+
### Workspace (Layer 1)
69+
[What was loaded. What's stale or missing.]
70+
71+
### Task (Layer 2)
72+
[Is intent clear? Is scope defined? Are success criteria present?]
73+
74+
### Action-Space / Action-Set (Layers 3-4)
75+
[Does a plan exist? Was it critiqued? Are critic issues addressed?]
76+
77+
### Coherence (Layer 5)
78+
[What modules are affected? Any known risks from traces?]
79+
80+
### Outcome (Layer 6)
81+
[Can we verify success? Are criteria testable?]
82+
83+
### Gaps
84+
[Bulleted list of what's missing or needs attention before proceeding]
85+
86+
### Recommendation
87+
[What to do next — address gaps, proceed to implementation, or ask specific questions]
88+
```
89+
90+
After printing the report, you are now loaded with full context for this task. The user can continue the conversation — ask questions, request implementation, ask you to address gaps, etc.
91+
92+
---
93+
94+
## Rules
95+
96+
1. **Read everything, don't skim.** The whole point is thorough context loading. Read the full desc.md, the full plan, the full critic. Don't summarize what you haven't read.
97+
2. **Be honest about gaps.** If the plan has unaddressed critic issues, say so. If the desc.md is vague, say so. Don't paper over problems.
98+
3. **Don't fix anything yet.** This command loads and reports. It doesn't modify files, create plans, or implement code. The user decides what to do next.
99+
4. **Stay concise in the report.** The report is a summary of what you loaded, not a reproduction of it. You've read everything — the knowledge is in your context now. The report tells the user what state things are in.

‎commands/devdocs-foundation-architecture.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# /devdocs-foundation-architecture — Propose Project Architecture
2+
3+
Read the simplified concepts and module proposal, then propose the most suitable architecture for the project. Priority is a solid foundation that can expand over time — not an immediate full-scope solution. The architecture should be as simple as possible while remaining extensible.
4+
5+
---
6+
7+
## Instructions
8+
9+
### Step 1: Read Context
10+
11+
Read:
12+
- `devdocs/concepts/simplified_concepts.md`
13+
- `devdocs/foundations/module_proposal.md`
14+
- `devdocs/foundations/known_requirements.md`
15+
- `devdocs/foundations/philosophy.md`
16+
17+
If any are missing, tell the user which commands to run first. At minimum, simplified concepts and module proposal must exist.
18+
19+
### Step 2: Evaluate Module Proposal
20+
21+
Before proposing architecture, critically evaluate the module proposal:
22+
23+
- **Accept modules** that represent genuine architectural boundaries
24+
- **Merge modules** that are over-split for prototype scope — if two modules would have 1-2 files each and always change together, merge them
25+
- **Reject modules** that are premature — if the project doesn't need the separation yet, don't build it yet
26+
27+
Document what you accepted, merged, or rejected and why. This is part of the architecture decision record.
28+
29+
### Step 3: Propose Architecture
30+
31+
Create `devdocs/foundations/architecture.md` with this structure:
32+
33+
```markdown
34+
# Architecture Proposal
35+
36+
## Design Philosophy
37+
38+
[One paragraph: what principles guided this architecture. Reference the project philosophy where relevant.]
39+
40+
## High-Level Overview
41+
42+
[ASCII diagram showing the major components, their relationships, and data flow direction]
43+
44+
## Module Decisions
45+
46+
### Accepted from module_proposal.md
47+
[List with brief reasoning]
48+
49+
### Merged
50+
[Which modules were combined and why]
51+
52+
### Rejected / Deferred
53+
[Which modules were dropped for now and why — with notes on when they'd become necessary]
54+
55+
## Components
56+
57+
### [Component Name]
58+
59+
**Responsibility:** one sentence
60+
**Key patterns:** what design patterns it uses and why (e.g., repository pattern for DB, facade for external services)
61+
**Interfaces:** what it exposes
62+
**Dependencies:** what it consumes
63+
**Expansion path:** how this component grows when moving from prototype to full scope
64+
65+
### [Component Name]
66+
...
67+
68+
## Design Patterns
69+
70+
[List the patterns used across the architecture and WHY each was chosen — not just the name but the problem it solves here]
71+
72+
## Data Flow
73+
74+
[Describe how data moves through the system — from input to storage to output. ASCII diagram if helpful.]
75+
76+
## What This Architecture Does NOT Handle (Yet)
77+
78+
[Explicitly list things that are out of scope for prototype but will need architectural support later. For each, note whether the current architecture can accommodate it or will need changes.]
79+
80+
## Key Trade-offs
81+
82+
[List the major trade-offs made and why. E.g., "chose simplicity over performance because the prototype won't have scale concerns." These are decisions future-you needs to understand.]
83+
```
84+
85+
### Step 4: Present for Review
86+
87+
Print the architecture proposal in the conversation. Highlight:
88+
- Total component count
89+
- The key trade-offs made
90+
- What was deferred and when it would become necessary
91+
92+
Remind the user:
93+
94+
> This architecture is designed for iterative development — solid enough to build on, simple enough to evolve. Check: (1) can you trace how each simplified concept maps to a component? (2) are the expansion paths realistic — or would growth require rewrites? (3) is anything over-engineered for prototype scope?
95+
96+
Save the file and confirm the path.
97+
98+
---
99+
100+
## Rules
101+
102+
1. **Simplicity over cleverness.** If a simpler pattern works, use it. Don't use a microservice architecture when a well-structured monolith will do. Don't use event sourcing when simple CRUD is sufficient.
103+
2. **Patterns must earn their place.** Every design pattern used must solve a specific problem in THIS project. "It's a best practice" is not enough. Name the problem it solves here.
104+
3. **Expansion paths must be additive.** Growing the prototype to full scope should mean adding code, not rewriting code. If a component would need restructuring at scale, note it explicitly.
105+
4. **Avoid tight coupling.** Components should communicate through defined interfaces. But don't over-abstract — a direct function call is better than an unnecessary abstraction layer.
106+
5. **Document what you deferred.** Future architects (including future-you) need to know what was deliberately left out and why.
107+
108+
---
109+
110+
## Output
111+
112+
- `devdocs/foundations/architecture.md`
113+
114+
Saved to disk + printed in conversation.

0 commit comments

Comments
 (0)