Skip to content

Commit 18492c3

Browse files
josealekhinejosealekhine
committed
docs(examples): update demo project to reflect current practices
- Add AGENT_PLAYBOOK.md with bootstrap instructions - Add LEARNINGS.md with example entries - Add PROMPT.md for Ralph Loop workflow - Add specs/ directory with oauth2.md example - Update existing context files with richer examples Signed-off-by: Jose Alekhinne <alekhinejose@gmail.com>
1 parent 316a782 commit 18492c3

11 files changed

Lines changed: 786 additions & 87 deletions

File tree

‎examples/demo/.context/AGENT_PLAYBOOK.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Agent Playbook
2+
3+
## Mental Model
4+
5+
This system does not persist experience.
6+
7+
- Each session is a fresh execution in a shared workshop.
8+
- Work continuity comes from artifacts left on the bench.
9+
10+
### Work → Reflect → Persist
11+
12+
After completing meaningful work, follow this cycle:
13+
14+
```
15+
┌─────────┐ ┌─────────┐ ┌─────────┐
16+
│ Work │ ──▶ │ Reflect │ ──▶ │ Persist │ ──▶ (continue)
17+
└─────────┘ └─────────┘ └─────────┘
18+
│
19+
▼
20+
Did I just...
21+
• Complete a task?
22+
• Make a decision?
23+
• Learn something?
24+
• Hit a milestone?
25+
```
26+
27+
**Don't wait for session end** — it may never come cleanly. Persist as you go.
28+
29+
## Read Order
30+
31+
1. CONSTITUTION.md — Hard rules, NEVER violate
32+
2. TASKS.md — What to work on next
33+
3. CONVENTIONS.md — How to write code
34+
4. ARCHITECTURE.md — Where things go
35+
5. DECISIONS.md — Why things are the way they are
36+
6. LEARNINGS.md — Gotchas to avoid
37+
38+
## How Your Memory Works
39+
40+
When asked "Do you remember?" or similar:
41+
42+
1. **Check the context files** (sessions/, TASKS.md, LEARNINGS.md, etc.)
43+
2. **Respond with what you found** — "From the sessions, I see we discussed X..."
44+
3. **Be honest about mechanism only if asked** — the user wants results, not disclaimers
45+
46+
**Wrong**: "I don't have memory, but I can check files. Want me to?"
47+
**Right**: *checks files* → "Yes, I see from the last session we were working on..."
48+
49+
The context IS your memory. Load it and use it — don't lead with caveats.
50+
51+
## Session History
52+
53+
Check `.context/sessions/` for session dumps from previous sessions.
54+
55+
Session files are named `YYYY-MM-DD-HHMMSS-<topic>.md`.
56+
57+
## When to Update Memory
58+
59+
| Event | Action |
60+
|-----------------------------|-----------------------|
61+
| Made architectural decision | Add to DECISIONS.md |
62+
| Discovered gotcha/bug | Add to LEARNINGS.md |
63+
| Established new pattern | Add to CONVENTIONS.md |
64+
| Completed task | Mark [x] in TASKS.md |
65+
| Had important discussion | Save to sessions/ |
66+
67+
### Prefer `ctx add` Over Direct File Edits
68+
69+
When adding learnings, decisions, or tasks, **use `ctx add` commands**:
70+
71+
```bash
72+
# ✓ Preferred - ensures consistent format, timestamps, structure
73+
ctx add learning "Title" --context "..." --lesson "..." --application "..."
74+
ctx add decision "Title" --context "..." --rationale "..." --consequences "..."
75+
ctx add task "Description"
76+
77+
# ✗ Avoid - bypasses structure, easy to write incomplete entries
78+
Edit LEARNINGS.md directly with a one-liner
79+
```
80+
81+
**Exception:** Direct edits are fine for:
82+
- Marking tasks complete (`[ ]` → `[x]`)
83+
- Minor corrections to existing entries
84+
85+
## Proactive Context Persistence
86+
87+
**Don't wait for session end** — persist context at natural milestones.
88+
89+
### Milestone Triggers
90+
91+
| Milestone | Action |
92+
|------------------------------------|-------------------------------------------------|
93+
| Complete a task | Mark done in TASKS.md, offer to add learnings |
94+
| Make an architectural decision | `ctx add decision "..."` |
95+
| Discover a gotcha or bug | `ctx add learning "..."` |
96+
| Finish a significant code change | Offer to summarize what was done |
97+
98+
### Self-Check Prompt
99+
100+
Periodically ask yourself:
101+
102+
> "If this session ended right now, would the next session know what happened?"
103+
104+
If no — persist something before continuing.
105+
106+
## How to Avoid Hallucinating Memory
107+
108+
Never assume: If you don't see it in files, you don't know it.
109+
110+
- Don't claim "we discussed X" without file evidence
111+
- Don't invent history - check sessions/ for actual discussions
112+
- If uncertain, say "I don't see this documented"
113+
- Trust files over intuition

‎examples/demo/.context/ARCHITECTURE.md‎

Lines changed: 76 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,72 @@
11
# Architecture
22

3-
System overview and key design decisions.
3+
System overview and component organization.
44

5-
## System Overview
5+
## High-Level Architecture
66

77
```
8-
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
9-
│ Frontend │───▶│ API Server │───▶│ Database │
10-
│ (React) │ │ (Go) │ │ (Postgres) │
11-
└──────────────┘ └──────────────┘ └──────────────┘
12-
│
13-
▼
14-
┌──────────────┐
15-
│ Redis Cache │
16-
└──────────────┘
8+
┌─────────────────────────────────────────────────────────────┐
9+
│ Clients │
10+
│ (Web App, Mobile App, CLI) │
11+
└─────────────────────────┬───────────────────────────────────┘
12+
│
13+
▼
14+
┌─────────────────────────────────────────────────────────────┐
15+
│ Load Balancer │
16+
│ (nginx / AWS ALB) │
17+
└─────────────────────────┬───────────────────────────────────┘
18+
│
19+
▼
20+
┌─────────────────────────────────────────────────────────────┐
21+
│ API Server │
22+
│ (Go / net/http) │
23+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
24+
│ │ Handlers │ │ Services │ │ Repositories │ │
25+
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
26+
└─────────────────────────┬───────────────────────────────────┘
27+
│
28+
┌───────────────┼───────────────┐
29+
▼ ▼ ▼
30+
┌───────────┐ ┌───────────┐ ┌───────────────┐
31+
│ PostgreSQL│ │ Redis │ │ Object Store │
32+
│ (primary) │ │ (cache) │ │ (S3) │
33+
└───────────┘ └───────────┘ └───────────────┘
1734
```
1835

1936
## Directory Structure
2037

21-
- `/cmd/` - Application entry points
22-
- `/internal/` - Private application code
23-
- `/pkg/` - Public library code
24-
- `/api/` - API definitions and OpenAPI specs
25-
- `/web/` - Frontend React application
38+
```
39+
.
40+
├── cmd/
41+
│ ├── api/ # API server entrypoint
42+
│ └── worker/ # Background worker entrypoint
43+
├── internal/
44+
│ ├── handler/ # HTTP handlers
45+
│ ├── service/ # Business logic
46+
│ ├── repository/ # Data access
47+
│ └── model/ # Domain types
48+
├── pkg/ # Shared libraries (importable)
49+
├── migrations/ # Database migrations
50+
├── docs/ # Documentation
51+
└── .context/ # AI context files
52+
```
53+
54+
## Key Components
55+
56+
### API Server (`cmd/api`)
57+
- Handles HTTP requests
58+
- Validates input, calls services, returns responses
59+
- Stateless — all state in database or cache
60+
61+
### Services (`internal/service`)
62+
- Contains business logic
63+
- Orchestrates multiple repositories
64+
- Enforces business rules
65+
66+
### Repositories (`internal/repository`)
67+
- Data access layer
68+
- One repository per aggregate root
69+
- Handles database queries and caching
2670

2771
## Key Patterns
2872

@@ -38,3 +82,19 @@ easier and components more modular.
3882
The system uses an event bus for decoupled component communication.
3983
Events are published when state changes, and interested components
4084
subscribe to relevant events.
85+
86+
## Data Flow
87+
88+
1. Request arrives at handler
89+
2. Handler validates input, extracts user context
90+
3. Handler calls service with validated data
91+
4. Service applies business logic, calls repositories
92+
5. Repository reads/writes to database
93+
6. Response flows back up the stack
94+
95+
## Scaling Strategy
96+
97+
- **Horizontal**: Add more API server instances behind load balancer
98+
- **Database**: Read replicas for read-heavy workloads
99+
- **Cache**: Redis for session data and frequently accessed records
100+
- **Background work**: Separate worker processes for async jobs

‎examples/demo/.context/CONSTITUTION.md‎

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,36 @@
11
# Constitution
22

3-
Core invariants that must NEVER be violated. Read these first.
3+
These rules are INVIOLABLE. If a task requires violating these, the task is wrong.
44

5-
## Inviolable Rules
5+
## Security Invariants
66

7-
- [ ] All code changes must include tests
8-
- [ ] Never commit secrets or credentials to the repository
9-
- [ ] Breaking changes require a deprecation period
10-
- [ ] Security vulnerabilities must be fixed within 24 hours
11-
- [ ] All public APIs must be documented
7+
- [ ] Never commit secrets, tokens, API keys, or credentials
8+
- [ ] Never store customer/user data in context files
9+
- [ ] All user input must be validated and sanitized
10+
11+
## Quality Invariants
12+
13+
- [ ] All code must pass tests before commit
14+
- [ ] No TODO comments in main branch (move to TASKS.md)
15+
- [ ] Breaking API changes require deprecation period
16+
17+
## Process Invariants
18+
19+
- [ ] All architectural changes require a decision record in DECISIONS.md
20+
21+
## TASKS.md Structure Invariants
22+
23+
TASKS.md must remain a replayable checklist. Uncheck all items and re-run
24+
the loop = verify/redo all tasks in order.
25+
26+
- [ ] **Never move tasks** — tasks stay in their Phase section permanently
27+
- [ ] **Never remove Phase headers** — Phase labels provide structure and order
28+
- [ ] **Never delete tasks** — mark as `[x]` completed, or `[-]` skipped with reason
29+
- [ ] **Use inline labels for status** — add `#in-progress` to task text, don't move it
30+
- [ ] **No "In Progress" sections** — these encourage moving tasks
31+
- [ ] **Ask before restructuring** — if structure changes seem needed, ask the user first
32+
33+
## Context Preservation Invariants
34+
35+
- [ ] **Archival is allowed, deletion is not** — use `ctx tasks archive` to move completed tasks, never delete context history
36+
- [ ] **Archive preserves structure** — archived tasks keep their Phase headers for traceability

‎examples/demo/.context/CONVENTIONS.md‎

Lines changed: 64 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,28 +2,82 @@
22

33
Coding standards and patterns used in this project.
44

5-
## Code Style
5+
## Naming
66

77
- Use camelCase for variables and functions
88
- Use PascalCase for types and interfaces
9+
- Use SCREAMING_SNAKE_CASE for constants
10+
11+
## Code Style
12+
913
- Prefer early returns over nested conditionals
1014
- Maximum line length: 100 characters
15+
- One component per file
1116

12-
## File Organization
17+
## Patterns
1318

14-
- One component per file
15-
- Group related files in directories
16-
- Test files should be adjacent to source files
19+
### Error Handling
20+
21+
Always return errors, never panic in library code:
22+
23+
```go
24+
// ✓ Correct
25+
func ProcessData(data []byte) (Result, error) {
26+
if len(data) == 0 {
27+
return Result{}, fmt.Errorf("empty data")
28+
}
29+
// ...
30+
}
31+
32+
// ✗ Wrong
33+
func ProcessData(data []byte) Result {
34+
if len(data) == 0 {
35+
panic("empty data") // Never panic in libraries
36+
}
37+
// ...
38+
}
39+
```
40+
41+
Wrap errors with context:
42+
43+
```go
44+
if err != nil {
45+
return fmt.Errorf("processing user %s: %w", userID, err)
46+
}
47+
```
48+
49+
### Configuration
50+
51+
Load order (highest priority first):
52+
1. Environment variables
53+
2. Config file (config.yaml)
54+
3. Default values
55+
56+
Log config source at startup for debuggability.
57+
58+
## Testing
59+
60+
- Test files adjacent to source files (`foo.go` → `foo_test.go`)
61+
- Use table-driven tests for multiple cases
62+
- Mock external dependencies, never call real services in tests
1763

1864
## Git Practices
1965

20-
- Commit messages follow Conventional Commits
66+
- Commit messages follow Conventional Commits format
2167
- Feature branches: `feature/<description>`
2268
- Bug fixes: `fix/<description>`
2369
- All PRs require at least one approval
2470

25-
## Error Handling
71+
## Documentation
72+
73+
### Doc-Impact Rule
74+
75+
When modifying code that affects user-facing behavior, update the corresponding
76+
documentation:
2677

27-
- Always return errors, never panic in libraries
28-
- Wrap errors with context using `fmt.Errorf`
29-
- Log errors at the boundary, not in helpers
78+
| Code Change | Doc Update Required |
79+
|--------------------------|------------------------|
80+
| API endpoint changes | `docs/api.md` |
81+
| CLI command changes | `docs/cli.md` |
82+
| Configuration changes | `docs/configuration.md`|
83+
| New features | `README.md` |

0 commit comments

Comments
 (0)