Skip to content

Commit f9f82db

Browse files
colbytimmcolbytimm
committed
feat: Implement structured memory management system with per-phase documentation
- Added workflow diagrams for project phases and memory management. - Created per-phase memory files (01-requirements.md to 16-customize.md) with structured templates. - Developed an index file for easy navigation of memory entries. - Updated generate.sh script to automate the creation of memory files and index. - Enhanced memory management instructions for phase transitions and archival processes.
1 parent 3c56635 commit f9f82db

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+2068
-174
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
CLAUDE.md

‎README.md‎

Lines changed: 123 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,123 +1,171 @@
11
# PromptLoom
22

3-
PromptLoom is a framework generator and workflow for AI-driven software development. It creates a complete directory structure, configuration files, prompt templates, and documentation to help teams use GitHub Copilot Chat and agent workflows for every phase of development.
3+
**Turn GitHub Copilot Chat into a full project teammate — scaffold your SDLC, guide your AI with phase-specific prompts, and capture decisions in structured memory** [See it in action →](./example)
44

5-
---
5+
Built for GitHub Copilot Chat. Interested in Cursor, Claude, or other agents? Open an issue to help prioritize first-class support.
66

7-
## What is PromptLoom?
7+
⸻
88

9-
PromptLoom sets up a Copilot-centric development environment, including:
10-
- Directory structure for prompts, config, memory, and ADRs
11-
- 16-phase prompt templates for Copilot Chat and agent workflows
12-
- Team and phase configuration files
13-
- Memory management and tagging system
14-
- Usage guides and workflow diagrams
9+
## Why PromptLoom?
10+
- **Clarity**: Each SDLC phase ships with a ready-to-run agent prompt.
11+
- **Consistency**: Standard structure for prompts, ADRs, tags, and governance.
12+
- **Low-drift memory**: Per-phase, source-linked memory reduces hallucinations.
13+
- **Flexible stacks**: Language-agnostic; you bind capabilities (not tools).
14+
- **Copilot-native**: Prompts and docs are tuned for GitHub Copilot Chat.
1515

16-
## Where does it work?
16+
⸻
1717

18-
PromptLoom is designed for TypeScript/React/Node.js projects, but is flexible for other stacks. It creates a `.github` folder for prompts, config, plus a `docs` folder for memory, ADRs, and framework guides.
18+
## How It Works (at a glance)
1919

20-
## Why use PromptLoom?
20+
```mermaid
21+
flowchart TD
22+
subgraph "Setup (Run once per project)"
23+
A[Run PromptLoom Setup Script] --> B[Scaffold Project Structure]
24+
end
2125
22-
### Consistency
26+
subgraph "Use (Daily development cycle)"
27+
C[Pick Phase Prompt] --> D[Work with Copilot Chat]
28+
D --> E[Produce Artifacts: Code, Docs, ADRs, Tests]
29+
end
2330
24-
Covers every development phase with clear instructions and templates.
31+
subgraph "Evolve (Continuous improvement)"
32+
F[Update Per-Phase Memory] --> G[Refine Outputs]
33+
G --> H[Continue Loop]
34+
end
2535
26-
### Collaboration
36+
B --> C
37+
E --> F
38+
H --> C
39+
```
2740

28-
Supports team workflows, memory sync, and documentation standards.
41+
**Setup**: Generate scaffolding once—get 16 prompts, configs, and memory structure
42+
**Use**: Pick any phase (requirements, architecture, testing, etc.) and work with Copilot to produce deliverables
43+
**Evolve**: Capture decisions in structured memory, refine your approach, and build on what worked
2944

30-
### Quality
45+
⸻
3146

32-
Enforces linting, testing, security checks, and ADRs.
47+
## Example Workflow
3348

34-
### AI Integration
49+
Here's how a typical development phase works—every phase prompt follows this pattern, whether it's requirements, architecture, testing, or deployment:
3550

36-
Optimized for Copilot Chat and agentic workflows.
51+
1. **Run phase prompt**: `/03-architecture` in Copilot Chat
52+
2. **AI generates deliverables**: Architecture diagrams, ADRs, component specs
53+
3. **Update memory**: Append structured entry to `docs/memory/03-architecture.md`
3754

38-
## How to Use
55+
Example memory entry structure:
56+
```yaml
57+
---
58+
phase: 03-architecture
59+
tags: [Architecture, Design, TechStack]
60+
sources: [docs/adr/20250809-system-architecture.md]
61+
confidence: high
62+
status: active
63+
---
3964

40-
### 1. Run the Setup Script Remotely (No Download Required)
65+
# Summary
66+
Selected microservices architecture with React frontend and Node.js APIs.
4167

42-
```bash
43-
bash <(curl -sSL https://raw.githubusercontent.com/Code-and-Sorts/PromptLoom/main/generate.sh)
68+
# Key Decisions
69+
- Decision: Microservices over monolith for team scaling
70+
- Rationale: Multiple teams can develop independently
71+
- Owner: Architecture Team
72+
- Date: 2025-08-09
73+
74+
# Evidence
75+
- Source: docs/adr/20250809-system-architecture.md
76+
- PR/Commit: #123 - Initial architecture implementation
77+
78+
# Open Questions
79+
- [ ] How will we handle database migrations in microservices?
80+
- [ ] Should we implement circuit breakers for service communication?
81+
82+
# Links
83+
- Related ADR: docs/adr/20250809-system-architecture.md
84+
- Related Doc: docs/architecture/overview.md
4485
```
4586
46-
You’ll be prompted for project name, team, tech stack, specializations, and custom tags. The script will generate all necessary folders and files in your current directory.
87+
See the full context in [example/docs/memory](./example/docs/memory).
4788
48-
**Prerequisites:**
49-
- Bash shell (macOS/Linux/WSL recommended)
50-
- GitHub Copilot Chat extension in VS Code for agent workflow
89+
⸻
5190
52-
**Note:** The setup script creates the directory structure and stub files. The actual content for requirements, user stories, architecture, etc. is generated interactively during each development phase using the prompt templates and Copilot Chat.
91+
## Quick Start
5392
54-
### 2. Review the Generated Structure
93+
### 1) Run the setup script (no download required)
5594
56-
- `.github/copilot-instructions.md` - Main development standards and workflow
57-
- `.github/prompts/` - 16 phase prompt templates for Copilot Chat and agent workflows
58-
- `.github/config/` - Team, phase, and tag configuration files
59-
- `docs/adr/` - Architecture Decision Records
60-
- `docs/memory.md` - Project memory and timeline
61-
- `docs/framework/` - Usage guide and workflow diagrams
95+
```bash
96+
bash <(curl -sSL https://raw.githubusercontent.com/Code-and-Sorts/PromptLoom/main/generate.sh)
97+
```
6298

63-
### 3. Start a Development Phase
99+
You'll be prompted for project name, team, tech stack, specializations, and tags.
64100

65-
- Open Copilot `Agent` Chat in VS Code
66-
- In the chat, type `/{promptName}` and run the prompt (ex. `/01-requirements`)
101+
**Advanced (optional) flags:**
102+
- `--cap-unit|--cap-e2e|--cap-contract|--cap-perf|--cap-docs|--cap-lint ""` to bind capabilities
103+
- `--suggest` to generate `capability_suggestions.yml` (advisory only)
104+
- `-y` to accept defaults, `--force` to overwrite
67105

68-
**Example Phase Prompt:**
106+
**Prerequisites:** Bash shell (macOS/Linux/WSL), and GitHub Copilot Chat in VS Code for the agent workflow.
69107

70-
```markdown
71-
# Requirements Gathering Phase
108+
### 2) Review what was generated
109+
- `.github/copilot-instructions.md` — standards, workflow, and capability bindings
110+
- `.github/prompts/` — 16 phase prompts for Copilot Chat (requirements → customize)
111+
- `.github/config/`
112+
- `team-config.yml`, `phase-config.yml`, `tags.yml`
113+
- `capabilities.yml` (bind commands you want agents to use; tools optional)
114+
- `capability_suggestions.yml` (only if `--suggest` used)
115+
- `docs/adr/` — Architecture Decision Records
116+
- `docs/memory/` — structured memory (per-phase files) + `index.md`
117+
- `docs/memory-archive/` — archived/pruned entries
118+
- `docs/framework/` — usage guide and workflow diagrams
72119

73-
You are a Business Analyst working on the project.
120+
### 3) Start a development phase with Copilot Chat
121+
- Open Copilot Chat in VS Code
122+
- Run a phase prompt, e.g. `/01-requirements`
123+
- Produce the artifacts listed in the prompt (docs, tests, code, ADRs)
124+
- Update memory: append a new entry to the relevant file in `docs/memory/` and add a one-liner to `docs/memory/index.md`
74125

75-
## Your Task
126+
⸻
76127

77-
1. Stakeholder Analysis
78-
2. Functional Requirements
79-
3. Non-functional Requirements
80-
4. Constraints
128+
## What You Get (the 60-second tour)
129+
- **16 prompts** covering the SDLC: Requirements, User Stories, Architecture, Docs, Implementation, Testing, Deployment, Release Notes, Security, Memory ops, Error Recovery, Integration Tests, Customization
130+
- **Capabilities-first config**: bind commands for unit/e2e/contract/perf/docs/lint in `capabilities.yml`—tools are suggestions, not mandates
131+
- **Structured memory**: per-phase files with frontmatter (phase, tags, sources, confidence, status) and sections (Summary, Decisions, Evidence, Questions, Links)
132+
- **Diagrams & docs**: Mermaid workflow, usage guide, and ADR scaffolding
81133

82-
## Output Format
134+
⸻
83135

84-
Create a comprehensive requirements document with:
85-
- Stakeholder Analysis
86-
- Functional Requirements
87-
- Non-functional Requirements
88-
- Constraints and Dependencies
89-
```
136+
## Where Does It Work?
90137

91-
### 4. Customize for Your Team
138+
**Tech Stacks**: PromptLoom is stack-agnostic—originally tuned for TypeScript/React/Node.js, but works with any language or framework (Python, Go, Java, .NET, Rust, etc.)
92139

93-
- Edit `.github/config/team-config.yml` for team standards and tags
94-
- Adjust prompt templates for your workflow
95-
- Use ADRs for architectural decisions
140+
**Team Sizes**: Works for solo developers, startups, and enterprise teams alike—the structured approach scales from individual projects to multi-team organizations
96141

97-
---
142+
**Project Types**: Suitable for web apps, APIs, mobile backends, CLI tools, libraries, and full-stack applications
98143

99-
## Documentation
144+
**AI Assistants**: Optimized for GitHub Copilot Chat today—if you want first-class support for other AI coding assistants (Cursor, Claude, etc.), please open an issue as community interest drives the roadmap
100145

101-
- **Usage Guide:** See `docs/framework/usage-guide.md` for step-by-step instructions
102-
- **Workflow Diagrams:** See `docs/framework/workflow-diagrams.md` for Mermaid visualizations
103-
- **Memory Management:** Follow tagging and update conventions in `docs/memory.md`
146+
⸻
104147

105-
---
148+
## Documentation
149+
- **Usage Guide**: `docs/framework/usage-guide.md` (phase-by-phase workflow)
150+
- **Workflow Diagram**: `docs/framework/workflow-diagrams.md`
151+
- **Memory**: See `docs/memory/index.md` and the per-phase files under `docs/memory/`
152+
- **ADRs**: Use `docs/adr/` to record architectural decisions
106153

107-
## Contributing
154+
⸻
108155

109-
Contributions are welcome! Please open issues or pull requests for improvements, bug fixes, or new features.
156+
## Contributing
110157

111-
## License
158+
Issues and PRs are welcome—especially for new prompts, diagrams, or agent integrations.
112159

113-
This project is licensed under the MIT License. See `LICENSE` for details.
160+
**Share with the community:**
161+
- Your own prompt templates, memory formats, or capability bindings
162+
- Generated scaffolds from real projects as "recipes" (see our [example](./example) for the format!)
163+
- Success stories and lessons learned from using PromptLoom
114164

115-
---
165+
Submit a PR or open an issue to add them to our shared library—we especially love seeing how different teams adapt the framework.
116166

117-
## Getting Help
167+
If you'd like support for Cursor/Claude/other agents, open a feature request.
118168

119-
- Review the usage guide and prompt templates
120-
- Check configuration files for standards and retention policies
121-
- Use Copilot Chat and agent mode for phase guidance and troubleshooting
169+
## License
122170

123-
---
171+
MIT. See `LICENSE`.

‎example/.github/config/capabilities.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
capabilities:
2+
unit_test:
3+
tool: null
4+
command: null
5+
notes: "Runs fast, isolated tests; target ≥80% coverage"
6+
e2e_test:
7+
tool: null
8+
command: null
9+
notes: "Covers critical user journeys end-to-end"
10+
contract_test:
11+
tool: null
12+
command: null
13+
notes: "Verifies producer/consumer API contracts"
14+
performance_test:
15+
tool: null
16+
command: null
17+
notes: "Establishes baseline throughput/latency with thresholds"
18+
docs_generator:
19+
tool: null
20+
command: null
21+
notes: "Builds API/code docs; fallback to Markdown stubs if unbound"
22+
linter:
23+
tool: null
24+
command: null
25+
notes: "Static analysis and style checks"
26+
policies:
27+
coverage_threshold: 0.80
28+
allow_unbound_capabilities: true

‎example/.github/config/phase-config.yml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
phases:
2+
"01-requirements":
3+
priority: critical
4+
estimatedTokens: 2000
5+
dependencies: []
6+
7+
"02-user-stories":
8+
priority: high
9+
estimatedTokens: 1500
10+
dependencies: ["01-requirements"]
11+
12+
"03-architecture":
13+
priority: critical
14+
estimatedTokens: 3000
15+
dependencies: ["01-requirements", "02-user-stories"]
16+
17+
"04-architecture-docs":
18+
priority: medium
19+
estimatedTokens: 1500
20+
dependencies: ["03-architecture"]
21+
22+
"05-implementation":
23+
priority: high
24+
estimatedTokens: 4000
25+
dependencies: ["03-architecture"]
26+
27+
"06-code-docs":
28+
priority: medium
29+
estimatedTokens: 1500
30+
dependencies: ["05-implementation"]
31+
32+
"07-testing":
33+
priority: high
34+
estimatedTokens: 2500
35+
dependencies: ["05-implementation"]
36+
37+
"08-deployment":
38+
priority: high
39+
estimatedTokens: 2000
40+
dependencies: ["07-testing"]
41+
42+
"09-release-notes":
43+
priority: medium
44+
estimatedTokens: 1000
45+
dependencies: ["08-deployment"]
46+
47+
"10-security":
48+
priority: critical
49+
estimatedTokens: 2500
50+
dependencies: ["05-implementation"]
51+
52+
"11-memory":
53+
priority: low
54+
estimatedTokens: 500
55+
dependencies: []
56+
57+
"12-memory-window":
58+
priority: low
59+
estimatedTokens: 500
60+
dependencies: ["11-memory"]
61+
62+
"13-memory-sync":
63+
priority: medium
64+
estimatedTokens: 1000
65+
dependencies: ["11-memory"]
66+
67+
"14-error-recovery":
68+
priority: high
69+
estimatedTokens: 1500
70+
dependencies: []
71+
72+
"15-integration-test":
73+
priority: high
74+
estimatedTokens: 2000
75+
dependencies: []
76+
77+
"16-customize":
78+
priority: medium
79+
estimatedTokens: 1500
80+
dependencies: []

‎example/.github/config/tags.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Tag Taxonomy for Memory Management
2+
3+
phases:
4+
- Requirements
5+
- UserStories
6+
- Architecture
7+
- Implementation
8+
- Testing
9+
- Deployment
10+
- Security
11+
- Release
12+
- Memory
13+
- Recovery
14+
15+
domains:
16+
- Frontend
17+
- Backend
18+
- Database
19+
- Infrastructure
20+
- DevOps
21+
- Security
22+
23+
priorities:
24+
- Critical
25+
- High
26+
- Medium
27+
- Low
28+
29+
custom:
30+
- Performance
31+
- UX
32+
- Security

0 commit comments

Comments
 (0)