Skip to content

Commit a2a0c97

Browse files
devakoneclaude
devakone
and
claude
committed
docs: add workflow capture system
- Workflow.md: project kickstart playbook with current process, automation targets, and metrics to track - WorkflowJournal.md: real-time capture of manual/repetitive/noteworthy actions during development - Updated Agents.md with workflow capture instructions for agents This project serves as both a product and a process learning tool. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 1c590f8 commit a2a0c97

3 files changed

Lines changed: 356 additions & 0 deletions

File tree

‎docs/Agents.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -527,4 +527,69 @@ MCP Supabase tools connect to remote projects, not local. For local development:
527527

528528
---
529529

530+
## Workflow Capture
531+
532+
**IMPORTANT:** This project is also a learning tool for improving the development process.
533+
534+
### When to Log
535+
536+
Add entries to `docs/WorkflowJournal.md` when you observe:
537+
538+
| Tag | When to Use |
539+
|-----|-------------|
540+
| `[MANUAL]` | User or agent did something by hand that could be scripted |
541+
| `[REPETITIVE]` | Did something that's been done in other projects |
542+
| `[FRICTION]` | Hit a snag, needed a workaround, or found unexpected complexity |
543+
| `[INSIGHT]` | Learned something worth remembering for future projects |
544+
| `[DECISION]` | Made a choice between alternatives (capture the reasoning) |
545+
546+
### Entry Format
547+
548+
```markdown
549+
### YYYY-MM-DD HH:MM - [TAG] Short title
550+
**Context:** What were you trying to do?
551+
**Action:** What did you actually do?
552+
**Time spent:** Estimate
553+
**Automation opportunity:** None | Low | Medium | High
554+
**Notes:** Any additional context
555+
```
556+
557+
### Examples of What to Capture
558+
559+
**Do log:**
560+
- Creating a new file that follows a pattern from other projects
561+
- Running a manual command that could be in a script
562+
- Discovering a gotcha or workaround
563+
- Choosing between libraries, approaches, or patterns
564+
- Anything that took longer than expected
565+
566+
**Don't log:**
567+
- Routine code edits
568+
- Standard git operations
569+
- Things already documented elsewhere
570+
571+
### Proactive Capture
572+
573+
When completing a task, briefly consider:
574+
1. Was any part of this manual when it could be automated?
575+
2. Have I done this exact thing in another project?
576+
3. Did I learn something that would help next time?
577+
578+
If yes to any, add a journal entry before moving on.
579+
580+
---
581+
582+
## Related Workflow Documents
583+
584+
| Document | Purpose |
585+
|----------|---------|
586+
| `docs/Workflow.md` | The playbook—how projects are started (template for future) |
587+
| `docs/WorkflowJournal.md` | Real-time capture during this project |
588+
| `docs/PRD.md` | Product requirements |
589+
| `docs/Agents.md` | This file—agent instructions |
590+
591+
The journal feeds insights back into the playbook. Over time, high-automation-opportunity items become scripts or templates.
592+
593+
---
594+
530595
*Last updated: Phase 0 initialization*

‎docs/Workflow.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# AI-Assisted Project Kickstart Playbook
2+
3+
**Purpose:** Capture how I start new projects so I can automate and refine the process over time.
4+
5+
**Living document:** This playbook evolves with each project. What starts as manual steps becomes scripts, templates, and agent prompts.
6+
7+
---
8+
9+
## Current Process (v1)
10+
11+
### Phase 1: Ideation & Requirements
12+
13+
| Step | Current Method | Automation Potential |
14+
|------|---------------|---------------------|
15+
| 1.1 | Draft idea across multiple AI tools (Perplexity, ChatGPT, Claude) | Medium - could create a structured prompt template |
16+
| 1.2 | Iterate on concept, compare outputs | Low - human judgment needed |
17+
| 1.3 | Consolidate into final PRD | High - PRD template + refinement prompt |
18+
19+
**Time spent:** Variable (hours to days)
20+
21+
**Artifacts produced:**
22+
- Initial concept notes
23+
- PRD draft (from preferred AI)
24+
- Final PRD (refined in Claude Code)
25+
26+
---
27+
28+
### Phase 2: Documentation Setup
29+
30+
| Step | Current Method | Automation Potential |
31+
|------|---------------|---------------------|
32+
| 2.1 | Refine PRD in Claude Code with implementation details | Medium - PRD expansion prompt |
33+
| 2.2 | Create Agents.md with project-specific rules | High - base template + customization |
34+
| 2.3 | Create Workflow.md (this file) | High - template |
35+
36+
**Time spent:** ~30 minutes
37+
38+
**Artifacts produced:**
39+
- `docs/PRD.md`
40+
- `docs/Agents.md`
41+
- `docs/Workflow.md`
42+
43+
---
44+
45+
### Phase 3: Infrastructure Setup
46+
47+
| Step | Current Method | Automation Potential |
48+
|------|---------------|---------------------|
49+
| 3.1 | Create GitHub repository (manual) | High - `gh repo create` |
50+
| 3.2 | Create Supabase project (manual) | Medium - Supabase CLI or API |
51+
| 3.3 | Create Vercel project (manual) | High - `vercel` CLI |
52+
| 3.4 | Configure environment variables (manual) | High - `.env.example` + script |
53+
| 3.5 | Link services together | Medium - scripted setup |
54+
55+
**Time spent:** ~20-30 minutes
56+
57+
**Artifacts produced:**
58+
- GitHub repo with initial commit
59+
- Supabase project (dev environment)
60+
- Vercel project linked to repo
61+
- `.env.local` configured
62+
63+
---
64+
65+
### Phase 4: Project Scaffolding
66+
67+
| Step | Current Method | Automation Potential |
68+
|------|---------------|---------------------|
69+
| 4.1 | Initialize Next.js project | High - `create-next-app` with preset |
70+
| 4.2 | Configure Tailwind, shadcn/ui | High - scripted |
71+
| 4.3 | Set up Supabase client | High - template files |
72+
| 4.4 | Create initial database schema | Medium - from PRD data model |
73+
| 4.5 | Set up auth flow | High - template |
74+
75+
**Time spent:** ~1-2 hours
76+
77+
**Artifacts produced:**
78+
- Working Next.js app
79+
- Database schema migration
80+
- Auth flow working
81+
82+
---
83+
84+
### Phase 5: Feature Implementation
85+
86+
| Step | Current Method | Automation Potential |
87+
|------|---------------|---------------------|
88+
| 5.1 | Create implementation tracker from PRD | High - extraction prompt |
89+
| 5.2 | Work with AI agents on each phase | Low - human oversight needed |
90+
| 5.3 | Review, test, iterate | Low - human judgment |
91+
| 5.4 | Deploy to preview/production | High - CI/CD |
92+
93+
**Time spent:** Variable (days to weeks)
94+
95+
---
96+
97+
## Automation Targets
98+
99+
### High Priority (Automate First)
100+
101+
1. **Project scaffold script**
102+
- Create GitHub repo
103+
- Initialize Next.js with my preferred config
104+
- Set up Supabase locally
105+
- Generate `.env.example` and `.env.local` templates
106+
- Create initial file structure
107+
108+
2. **Documentation templates**
109+
- PRD template with standard sections
110+
- Agents.md base template
111+
- Workflow.md template
112+
113+
3. **Environment setup**
114+
- Vercel project creation + linking
115+
- Environment variable scaffolding
116+
117+
### Medium Priority (Template + Customize)
118+
119+
1. **PRD expansion prompt** - Take rough idea → full PRD
120+
2. **Database schema generator** - PRD data model → SQL migration
121+
3. **Supabase project creation** - Via management API
122+
123+
### Low Priority (Keep Manual)
124+
125+
1. Initial ideation across AI tools
126+
2. Final human review of generated code
127+
3. Product decisions and tradeoffs
128+
129+
---
130+
131+
## Metrics to Track
132+
133+
As I build projects, capture:
134+
135+
| Metric | Why It Matters |
136+
|--------|---------------|
137+
| Time from idea to first commit | Overall efficiency |
138+
| Time on manual setup tasks | Automation opportunities |
139+
| Number of AI agent turns per feature | Prompt quality |
140+
| Errors caught in review | Agent reliability |
141+
| Steps repeated across projects | Template candidates |
142+
143+
---
144+
145+
## Future Vision
146+
147+
**Goal:** Reduce project kickstart from hours to minutes.
148+
149+
```
150+
Input: Project idea + type (SaaS, CLI, API, etc.)
151+
Output:
152+
- GitHub repo with scaffold
153+
- Supabase project configured
154+
- Vercel project linked
155+
- PRD + Agents.md generated
156+
- First migration ready
157+
- Ready for feature implementation
158+
```
159+
160+
---
161+
162+
## Revision History
163+
164+
| Version | Date | Changes |
165+
|---------|------|---------|
166+
| v1 | 2025-01-16 | Initial process capture from Bolokono kickstart |
167+
168+
---
169+
170+
*This document is the source of truth for how I start projects. Update it as the process improves.*

‎docs/WorkflowJournal.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Workflow Journal: Bolokono
2+
3+
**Purpose:** Real-time capture of manual, repetitive, and noteworthy actions during development. This feeds back into improving the Workflow Playbook.
4+
5+
---
6+
7+
## How to Use This Journal
8+
9+
Agents and humans add entries when:
10+
- **[MANUAL]** - Did something by hand that could be automated
11+
- **[REPETITIVE]** - Did something we've done before in other projects
12+
- **[FRICTION]** - Hit a snag, workaround, or unexpected complexity
13+
- **[INSIGHT]** - Learned something worth remembering
14+
- **[DECISION]** - Made a choice between alternatives (capture the why)
15+
16+
Format:
17+
```markdown
18+
### YYYY-MM-DD HH:MM - [TAG] Short title
19+
**Context:** What were you trying to do?
20+
**Action:** What did you actually do?
21+
**Time spent:** Estimate
22+
**Automation opportunity:** None | Low | Medium | High
23+
**Notes:** Any additional context
24+
```
25+
26+
---
27+
28+
## Journal Entries
29+
30+
### 2025-01-16 - [MANUAL] Created GitHub repository
31+
**Context:** Needed a repo for the project
32+
**Action:** Manually created https://github.com/devakone/bolokonon via GitHub web UI
33+
**Time spent:** 2 minutes
34+
**Automation opportunity:** High - `gh repo create devakone/bolokonon --public --description "Analyze git history to reveal developer craftsmanship patterns"`
35+
**Notes:** Could be part of a kickstart script
36+
37+
---
38+
39+
### 2025-01-16 - [MANUAL] Created Supabase project
40+
**Context:** Need database and auth for the app
41+
**Action:** Manually created project via Supabase dashboard
42+
**Time spent:** 3 minutes
43+
**Automation opportunity:** Medium - Supabase Management API can create projects, but requires org setup
44+
**Notes:** Need to capture the project ref once created
45+
46+
---
47+
48+
### 2025-01-16 - [REPETITIVE] Wrote .gitignore
49+
**Context:** Every project needs a .gitignore
50+
**Action:** Created standard Next.js/Supabase .gitignore
51+
**Time spent:** 1 minute (AI generated)
52+
**Automation opportunity:** High - Should be in project template
53+
**Notes:** Same patterns used in most projects
54+
55+
---
56+
57+
### 2025-01-16 - [REPETITIVE] Created Agents.md structure
58+
**Context:** Need agent instructions for AI-assisted development
59+
**Action:** Adapted from previous project (Sabati) with Bolokono-specific changes
60+
**Time spent:** 10 minutes
61+
**Automation opportunity:** High - Base template exists, just needs project-specific customization
62+
**Notes:** Core sections are the same: Database Access, Migrations, Commits, Quality Checklist
63+
64+
---
65+
66+
### 2025-01-16 - [INSIGHT] PRD iteration across multiple AI tools
67+
**Context:** Drafting the initial product concept
68+
**Action:** Used Perplexity → ChatGPT → Claude to iterate on the idea
69+
**Time spent:** Variable
70+
**Automation opportunity:** Low - The value is in the different perspectives
71+
**Notes:** Each tool has strengths. Perplexity for research, ChatGPT for broad exploration, Claude for implementation detail. Worth keeping this multi-tool approach.
72+
73+
---
74+
75+
### 2025-01-16 - [DECISION] Edge Functions vs External Worker
76+
**Context:** Need to run analysis jobs
77+
**Action:** Chose Supabase Edge Functions for Phase 0-1, with option to move to external worker for Phase 2+
78+
**Time spent:** N/A (part of PRD)
79+
**Automation opportunity:** None
80+
**Notes:** Edge Functions have 60s timeout. Fine for < 1000 commits. Will need worker for large repos.
81+
82+
---
83+
84+
## Pending Entries
85+
86+
*Add items here during development, then format them properly:*
87+
88+
- [ ] Vercel project creation
89+
- [ ] Environment variable setup
90+
- [ ] Next.js initialization
91+
- [ ] Supabase local setup
92+
- [ ] First migration creation
93+
- [ ] OAuth configuration
94+
95+
---
96+
97+
## Summary Statistics
98+
99+
*Updated periodically:*
100+
101+
| Tag | Count | Total Time | High Automation |
102+
|-----|-------|------------|-----------------|
103+
| MANUAL | 2 | ~5 min | 2 |
104+
| REPETITIVE | 2 | ~11 min | 2 |
105+
| FRICTION | 0 | - | - |
106+
| INSIGHT | 1 | - | - |
107+
| DECISION | 1 | - | - |
108+
109+
---
110+
111+
## Patterns Emerging
112+
113+
*Observations that might inform the playbook:*
114+
115+
1. **Documentation setup is highly templatable** - PRD structure, Agents.md base, Workflow.md are all reusable
116+
2. **Infrastructure creation is manual but scriptable** - GitHub, Supabase, Vercel all have CLIs/APIs
117+
3. **Multi-tool ideation is valuable** - Different AI tools contribute differently; keep this human-driven
118+
119+
---
120+
121+
*Last updated: 2025-01-16*

0 commit comments

Comments
 (0)