@abarcenas/ai-workflow-template 1.14.0 → 1.15.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/.agents/instructions/task-implementation.instructions.md +66 -163
- package/AGENTS.md +1 -1
- package/package.json +1 -1
- package/scripts/sync.js +84 -1
|
@@ -1,211 +1,114 @@
|
|
|
1
1
|
---
|
|
2
|
-
applyTo: "
|
|
3
|
-
description: "Instructions for implementing
|
|
2
|
+
applyTo: "**/memory-bank/tasks/*.md"
|
|
3
|
+
description: "Instructions for implementing tasks using the memory-bank task management system"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
# Task
|
|
6
|
+
# Task Implementation Instructions
|
|
7
7
|
|
|
8
|
-
You
|
|
8
|
+
You implement tasks using the memory-bank task management system. Each task has a dedicated file in `memory-bank/tasks/`. Progress is tracked across three levels: the individual task file, `activeContext.md`, and `progress.md`.
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
## Core Implementation Process
|
|
13
|
-
|
|
14
|
-
### Markdown Audit Trail
|
|
10
|
+
## Memory Bank Audit Trail
|
|
15
11
|
|
|
16
12
|
All planning, implementation, and execution work must be recorded in Markdown files.
|
|
17
13
|
|
|
18
|
-
-
|
|
14
|
+
- The task file in `memory-bank/tasks/` is the single source of truth for that task's plan, decisions, and progress.
|
|
15
|
+
- Update `activeContext.md` when switching focus or making significant changes.
|
|
16
|
+
- Update `progress.md` when project-wide status changes (new features working, blockers, etc.).
|
|
19
17
|
- Do not rely on chat alone for durable tracking of implementation decisions or progress.
|
|
20
|
-
- Treat the Markdown record as the source of truth for auditability and session recovery.
|
|
21
|
-
|
|
22
|
-
### 1. Plan Analysis and Preparation
|
|
23
|
-
|
|
24
|
-
**MUST complete before starting implementation:**
|
|
25
|
-
|
|
26
|
-
- **MANDATORY**: Read and fully understand the complete plan file including scope, objectives, all phases, and every checklist item
|
|
27
|
-
- **MANDATORY**: Read and fully understand the corresponding changes file completely - if any parts are missing from context, read the entire file back in using `read_file`
|
|
28
|
-
- **MANDATORY**: Identify all referenced files mentioned in the plan and examine them for context
|
|
29
|
-
- **MANDATORY**: Understand current project structure and conventions
|
|
30
|
-
|
|
31
|
-
### 2. Systematic Implementation Process
|
|
32
18
|
|
|
33
|
-
**
|
|
19
|
+
**Task file format**: See `memory-bank.instructions.md` for the complete task file structure (sections, progress log, subtask table, etc.).
|
|
34
20
|
|
|
35
|
-
1.
|
|
36
|
-
2. **MANDATORY before implementing any task:**
|
|
37
|
-
- **ALWAYS ensure implementation is associated with a specific task from the plan**
|
|
38
|
-
- **ALWAYS read the entire details section for that task from the associated details markdown file in `.copilot-tracking/details/**`\*\*
|
|
39
|
-
- **FULLY understand all implementation details before proceeding**
|
|
40
|
-
- Gather any additional required context as needed
|
|
21
|
+
## 1. Setup
|
|
41
22
|
|
|
42
|
-
|
|
43
|
-
- Follow existing code patterns and conventions from the workspace
|
|
44
|
-
- Create working functionality that meets all task requirements specified in the details
|
|
45
|
-
- Include proper error handling, documentation, and follow best practices
|
|
46
|
-
|
|
47
|
-
4. **Mark task complete and update changes tracking:**
|
|
48
|
-
- Update plan file: change `[ ]` to `[x]` for completed task
|
|
49
|
-
- **MANDATORY after completing EVERY task**: Update the changes file by appending to the appropriate Added, Modified, or Removed sections with relative file paths and one-sentence summary of what was implemented
|
|
50
|
-
- **MANDATORY**: If any changes diverge from the task plan and details, specifically call out within the relevant section that the change was made outside of the plan and include the specific reason
|
|
51
|
-
- If ALL tasks in a phase are complete `[x]`, mark the phase header as complete `[x]`
|
|
23
|
+
**MUST complete before starting implementation:**
|
|
52
24
|
|
|
53
|
-
|
|
25
|
+
1. Read `memory-bank/activeContext.md` to understand current focus and recent changes
|
|
26
|
+
2. Read `memory-bank/progress.md` to understand project-wide status
|
|
27
|
+
3. Read `memory-bank/tasks/_index.md` to find the task assigned to you
|
|
28
|
+
4. Read the full task file in `memory-bank/tasks/` — understand the request, thought process, implementation plan, and all subtasks
|
|
29
|
+
5. Identify referenced files mentioned in the task and examine them for context
|
|
30
|
+
6. Understand current project structure and conventions
|
|
31
|
+
|
|
32
|
+
## 2. Systematic Implementation Process
|
|
33
|
+
|
|
34
|
+
**Implement each task systematically:**
|
|
35
|
+
|
|
36
|
+
1. **Process subtasks in order** — Follow the task file's subtask sequence exactly, one step at a time
|
|
37
|
+
2. **Before implementing any subtask:**
|
|
38
|
+
- Fully understand all implementation requirements from the task file
|
|
39
|
+
- Gather any additional required context
|
|
40
|
+
3. **Implement the subtask completely with working code:**
|
|
41
|
+
- Follow existing code patterns and conventions
|
|
42
|
+
- Create working functionality that meets all requirements
|
|
43
|
+
- Include proper error handling and documentation
|
|
44
|
+
4. **After every subtask:**
|
|
45
|
+
- Mark the subtask complete in the task file's subtask table
|
|
46
|
+
- Add a progress log entry with date, what was done, challenges, and decisions
|
|
47
|
+
- Update the overall task status and completion percentage
|
|
48
|
+
- Update `memory-bank/activeContext.md` with recent changes and next steps
|
|
49
|
+
- Update `memory-bank/tasks/_index.md` to reflect status changes
|
|
50
|
+
|
|
51
|
+
## 3. Implementation Quality Standards
|
|
54
52
|
|
|
55
53
|
**Every implementation MUST:**
|
|
56
54
|
|
|
57
|
-
- Follow existing workspace patterns and conventions
|
|
55
|
+
- Follow existing workspace patterns and conventions
|
|
58
56
|
- Implement complete, working functionality that meets all task requirements
|
|
59
57
|
- Include appropriate error handling and validation
|
|
60
58
|
- Use consistent naming conventions and code structure from the workspace
|
|
61
|
-
- Add necessary documentation
|
|
59
|
+
- Add necessary documentation for complex logic
|
|
62
60
|
- Ensure compatibility with existing systems and dependencies
|
|
63
61
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
**After implementing each task:**
|
|
67
|
-
|
|
68
|
-
1. Validate the changes made against the task requirements from the details file
|
|
69
|
-
2. Fix any problems before moving to the next task
|
|
70
|
-
3. **MANDATORY**: Update the plan file to mark completed tasks `[x]`
|
|
71
|
-
4. **MANDATORY after EVERY task completion**: Update the changes file by appending to Added, Modified, or Removed sections with relative file paths and one-sentence summary of what was implemented
|
|
72
|
-
5. Continue to the next unchecked task
|
|
73
|
-
|
|
74
|
-
**Continue until:**
|
|
75
|
-
|
|
76
|
-
- All tasks in the plan are marked complete `[x]`
|
|
77
|
-
- All specified files have been created or updated with working code
|
|
78
|
-
- All success criteria from the plan have been verified
|
|
79
|
-
|
|
80
|
-
### 5. Reference Gathering Guidelines
|
|
81
|
-
|
|
82
|
-
**When gathering external references:**
|
|
83
|
-
|
|
84
|
-
- Focus on practical implementation examples over theoretical documentation
|
|
85
|
-
- Validate that external sources contain actual usable patterns
|
|
86
|
-
- Adapt external patterns to match workspace conventions and standards
|
|
87
|
-
|
|
88
|
-
**When implementing from references:**
|
|
89
|
-
|
|
90
|
-
- Follow workspace patterns and conventions first, external patterns second
|
|
91
|
-
- Implement complete, working functionality rather than just examples
|
|
92
|
-
- Ensure all dependencies and configurations are properly integrated
|
|
93
|
-
- Ensure implementations work within the existing project structure
|
|
94
|
-
|
|
95
|
-
### 6. Completion and Documentation
|
|
62
|
+
## 4. Completion
|
|
96
63
|
|
|
97
64
|
**Implementation is complete when:**
|
|
98
65
|
|
|
99
|
-
- All
|
|
66
|
+
- All subtasks in the task file are marked complete
|
|
100
67
|
- All specified files exist with working code
|
|
101
|
-
- All success criteria from the
|
|
68
|
+
- All success criteria from the task are verified
|
|
102
69
|
- No implementation errors remain
|
|
103
70
|
|
|
104
|
-
**Final
|
|
71
|
+
**Final steps:**
|
|
105
72
|
|
|
106
|
-
-
|
|
107
|
-
|
|
73
|
+
1. Update `memory-bank/progress.md` — document what now works, what's left to build, and any known issues
|
|
74
|
+
2. Update `memory-bank/activeContext.md` — summarize what was implemented and set next steps
|
|
75
|
+
3. Update `memory-bank/tasks/_index.md` — mark the task file as Completed
|
|
76
|
+
4. Mark the task's overall status to Completed in its own file
|
|
108
77
|
|
|
109
|
-
|
|
78
|
+
## 5. Problem Resolution
|
|
110
79
|
|
|
111
80
|
**When encountering implementation issues:**
|
|
112
81
|
|
|
113
|
-
- Document the specific problem clearly
|
|
82
|
+
- Document the specific problem clearly in the task file's progress log
|
|
114
83
|
- Try alternative approaches or search terms
|
|
115
84
|
- Use workspace patterns as fallback when external references fail
|
|
116
85
|
- Continue with available information rather than stopping completely
|
|
117
|
-
- Note any unresolved issues in the
|
|
86
|
+
- Note any unresolved issues in the task file for future reference
|
|
118
87
|
|
|
119
88
|
## Implementation Workflow
|
|
120
89
|
|
|
121
90
|
```
|
|
122
|
-
1. Read
|
|
123
|
-
2.
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
4. Repeat until all tasks complete
|
|
133
|
-
5. Only after ALL phases are complete [x]: Add final Release Summary to changes file
|
|
91
|
+
1. Read activeContext.md, progress.md, tasks/_index.md, and the assigned task file
|
|
92
|
+
2. For each unchecked subtask:
|
|
93
|
+
a. Fully understand requirements
|
|
94
|
+
b. Implement with working code following workspace patterns
|
|
95
|
+
c. Validate implementation meets requirements
|
|
96
|
+
d. Mark subtask complete in task file
|
|
97
|
+
e. Add progress log entry to task file with date and details
|
|
98
|
+
f. Update activeContext.md and _index.md
|
|
99
|
+
3. Repeat until all subtasks complete
|
|
100
|
+
4. Update progress.md, activeContext.md, _index.md with final status
|
|
134
101
|
```
|
|
135
102
|
|
|
136
103
|
## Success Criteria
|
|
137
104
|
|
|
138
105
|
Implementation is complete when:
|
|
139
106
|
|
|
140
|
-
- ✅ All
|
|
107
|
+
- ✅ All subtasks in the task file are marked complete
|
|
141
108
|
- ✅ All specified files contain working code
|
|
142
109
|
- ✅ Code follows workspace patterns and conventions
|
|
143
110
|
- ✅ All functionality works as expected within the project
|
|
144
|
-
- ✅
|
|
145
|
-
- ✅
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
Use the following as a template for the changes file that tracks implementation progress for releases.
|
|
150
|
-
Replace `{{ }}` with appropriate values. Create this file in `./.copilot-tracking/changes/` with filename: `YYYYMMDD-task-description-changes.md`
|
|
151
|
-
|
|
152
|
-
**IMPORTANT**: Update this file after EVERY task completion by appending to Added, Modified, or Removed sections.
|
|
153
|
-
**MANDATORY**: Always include the following at the top of the changes file: `<!-- markdownlint-disable-file -->`
|
|
154
|
-
|
|
155
|
-
<!-- <changes-template> -->
|
|
156
|
-
|
|
157
|
-
```markdown
|
|
158
|
-
<!-- markdownlint-disable-file -->
|
|
159
|
-
|
|
160
|
-
# Release Changes: {{task name}}
|
|
161
|
-
|
|
162
|
-
**Related Plan**: {{plan-file-name}}
|
|
163
|
-
**Implementation Date**: {{YYYY-MM-DD}}
|
|
164
|
-
|
|
165
|
-
## Summary
|
|
166
|
-
|
|
167
|
-
{{Brief description of the overall changes made for this release}}
|
|
168
|
-
|
|
169
|
-
## Changes
|
|
170
|
-
|
|
171
|
-
### Added
|
|
172
|
-
|
|
173
|
-
- {{relative-file-path}} - {{one sentence summary of what was implemented}}
|
|
174
|
-
|
|
175
|
-
### Modified
|
|
176
|
-
|
|
177
|
-
- {{relative-file-path}} - {{one sentence summary of what was changed}}
|
|
178
|
-
|
|
179
|
-
### Removed
|
|
180
|
-
|
|
181
|
-
- {{relative-file-path}} - {{one sentence summary of what was removed}}
|
|
182
|
-
|
|
183
|
-
## Release Summary
|
|
184
|
-
|
|
185
|
-
**Total Files Affected**: {{number}}
|
|
186
|
-
|
|
187
|
-
### Files Created ({{count}})
|
|
188
|
-
|
|
189
|
-
- {{file-path}} - {{purpose}}
|
|
190
|
-
|
|
191
|
-
### Files Modified ({{count}})
|
|
192
|
-
|
|
193
|
-
- {{file-path}} - {{changes-made}}
|
|
194
|
-
|
|
195
|
-
### Files Removed ({{count}})
|
|
196
|
-
|
|
197
|
-
- {{file-path}} - {{reason}}
|
|
198
|
-
|
|
199
|
-
### Dependencies & Infrastructure
|
|
200
|
-
|
|
201
|
-
- **New Dependencies**: {{list-of-new-dependencies}}
|
|
202
|
-
- **Updated Dependencies**: {{list-of-updated-dependencies}}
|
|
203
|
-
- **Infrastructure Changes**: {{infrastructure-updates}}
|
|
204
|
-
- **Configuration Updates**: {{configuration-changes}}
|
|
205
|
-
|
|
206
|
-
### Deployment Notes
|
|
207
|
-
|
|
208
|
-
{{Any specific deployment considerations or steps}}
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
<!-- </changes-template> -->
|
|
111
|
+
- ✅ Task progress log documents what was done, challenges, and decisions
|
|
112
|
+
- ✅ activeContext.md reflects the latest changes and next steps
|
|
113
|
+
- ✅ progress.md reflects the updated project status
|
|
114
|
+
- ✅ tasks/_index.md shows the task as Completed
|
package/AGENTS.md
CHANGED
|
@@ -13,7 +13,7 @@ This project includes AI-assisted development configuration distributed through
|
|
|
13
13
|
|
|
14
14
|
1. **Understand before acting** — Read relevant instructions from `.agents/instructions/` before working with specific technologies
|
|
15
15
|
2. **Plan before implementing** — Use `.agents/agents/plan.agent.md` or `.agents/agents/implementation-plan.agent.md` patterns for structured work
|
|
16
|
-
3. **Track progress** — Update
|
|
16
|
+
3. **Track progress** — Update `memory-bank/activeContext.md` and `memory-bank/progress.md` after each task (see `.agents/instructions/task-implementation.instructions.md`)
|
|
17
17
|
4. **Maintain context** — Keep memory bank files updated (see `.agents/instructions/memory-bank.instructions.md`)
|
|
18
18
|
|
|
19
19
|
## Instructions Reference
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@abarcenas/ai-workflow-template",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.15.0",
|
|
4
4
|
"description": "A comprehensive template repository for AI-assisted development workflows using GitHub Copilot. This template provides a structured approach to leveraging AI assistance through pre-configured skills, prompts, agents, and coding standards.",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"scripts": {
|
package/scripts/sync.js
CHANGED
|
@@ -157,9 +157,92 @@ for (const rootFile of rootFiles) {
|
|
|
157
157
|
console.warn(`[ai-workflow-template] Skipped locally modified root file: ${rootFile}`)
|
|
158
158
|
}
|
|
159
159
|
|
|
160
|
+
/* ── Scaffold memory-bank/ directory ──────────────────────────── */
|
|
161
|
+
|
|
162
|
+
const memoryBankStubs = {
|
|
163
|
+
'projectbrief.md': `# projectbrief
|
|
164
|
+
|
|
165
|
+
> Foundation document — defines core requirements and goals.
|
|
166
|
+
|
|
167
|
+
- **Purpose**: {{describe project purpose}}
|
|
168
|
+
- **Goals**: {{list project goals}}
|
|
169
|
+
- **Scope**: {{define scope}}
|
|
170
|
+
`,
|
|
171
|
+
'productContext.md': `# productContext
|
|
172
|
+
|
|
173
|
+
> Why this project exists and what problems it solves.
|
|
174
|
+
|
|
175
|
+
- **Problem**: {{describe the problem}}
|
|
176
|
+
- **Solution**: {{describe the solution}}
|
|
177
|
+
- **User Experience**: {{describe UX goals}}
|
|
178
|
+
`,
|
|
179
|
+
'activeContext.md': `# activeContext
|
|
180
|
+
|
|
181
|
+
> Current work focus, recent changes, next steps.
|
|
182
|
+
|
|
183
|
+
- **Current Focus**: {{current task or goal}}
|
|
184
|
+
- **Recent Changes**: {{list of recent changes}}
|
|
185
|
+
- **Next Steps**: {{next actions}}
|
|
186
|
+
`,
|
|
187
|
+
'systemPatterns.md': `# systemPatterns
|
|
188
|
+
|
|
189
|
+
> Architecture, key decisions, design patterns.
|
|
190
|
+
|
|
191
|
+
- **Architecture**: {{describe architecture}}
|
|
192
|
+
- **Key Decisions**: {{list key technical decisions}}
|
|
193
|
+
- **Patterns**: {{list design patterns in use}}
|
|
194
|
+
`,
|
|
195
|
+
'techContext.md': `# techContext
|
|
196
|
+
|
|
197
|
+
> Technologies, setup, constraints, dependencies.
|
|
198
|
+
|
|
199
|
+
- **Stack**: {{list technologies}}
|
|
200
|
+
- **Setup**: {{describe dev setup}}
|
|
201
|
+
- **Constraints**: {{list technical constraints}}
|
|
202
|
+
`,
|
|
203
|
+
'progress.md': `# progress
|
|
204
|
+
|
|
205
|
+
> What works, what's left, current status.
|
|
206
|
+
|
|
207
|
+
- **Working**: {{what's implemented and working}}
|
|
208
|
+
- **To Build**: {{what remains}}
|
|
209
|
+
- **Status**: {{overall project status}}
|
|
210
|
+
- **Known Issues**: {{list known issues}}
|
|
211
|
+
`,
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
const memoryBankDir = resolve(consumerRoot, 'memory-bank')
|
|
215
|
+
let scaffolded = 0
|
|
216
|
+
|
|
217
|
+
for (const [fileName, fileContent] of Object.entries(memoryBankStubs)) {
|
|
218
|
+
const targetFile = resolve(memoryBankDir, fileName)
|
|
219
|
+
const trackedKey = `__memory-bank__/${fileName}`
|
|
220
|
+
|
|
221
|
+
if (existsSync(targetFile)) {
|
|
222
|
+
continue
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
ensureParentDirectory(targetFile)
|
|
226
|
+
writeFileSync(targetFile, fileContent, 'utf8')
|
|
227
|
+
manifest.files[trackedKey] = hashFile(targetFile)
|
|
228
|
+
scaffolded += 1
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/* ── Auto-copy opencode.mcp.json from example ────────────────── */
|
|
232
|
+
|
|
233
|
+
const exampleMcpFile = resolve(packageRoot, 'opencode.mcp.example.json')
|
|
234
|
+
const targetMcpFile = resolve(consumerRoot, 'opencode.mcp.json')
|
|
235
|
+
const mcpTrackedKey = '__root__/opencode.mcp.json'
|
|
236
|
+
|
|
237
|
+
if (existsSync(exampleMcpFile) && !existsSync(targetMcpFile)) {
|
|
238
|
+
copyFileSync(exampleMcpFile, targetMcpFile)
|
|
239
|
+
manifest.files[mcpTrackedKey] = hashFile(targetMcpFile)
|
|
240
|
+
scaffolded += 1
|
|
241
|
+
}
|
|
242
|
+
|
|
160
243
|
if (!dryRun) {
|
|
161
244
|
writeManifest(manifest)
|
|
162
245
|
}
|
|
163
246
|
|
|
164
247
|
const modeLabel = forceOverwrite ? 'force' : dryRun ? 'dry-run' : 'safe'
|
|
165
|
-
console.log(`[ai-workflow-template] Synced ${copied} files (${added} new), skipped ${skipped} modified files. Mode: ${modeLabel}.`)
|
|
248
|
+
console.log(`[ai-workflow-template] Synced ${copied} files (${added} new), scaffolded ${scaffolded} files, skipped ${skipped} modified files. Mode: ${modeLabel}.`)
|