Skip to content

Commit bc0624d

Browse files
plitzenbergerplitzenberger
committed
docs(requirements): restructure vault with kanban boards and agent workflow
Evolve the Obsidian requirements vault from flat files to a feature-folder hierarchy with two-level Kanban boards for AI agent handoff between requirements and implementation phases. - Add Main Board.md (master Kanban) tracking features/epics - Add per-feature board.md files for implementation ticket tracking - Migrate existing specs into Features/ folder structure - Add Templates/ with requirement spec and ticket templates - Add glossary with shared terminology and agent role definitions - Add obsidian-kanban plugin config for board rendering - Rewrite SKILL.md with vault conventions, board update protocol, and requirements/implementation agent workflows Made-with: Cursor
1 parent 5e9fe61 commit bc0624d

20 files changed

Lines changed: 677 additions & 16 deletions

File tree

‎.agents/skills/obsidian-requirements/SKILL.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
name: obsidian-requirements
3+
description: Work with the Obsidian requirements vault in docs/requirements/. Use when creating, editing, or reviewing product requirement documents, feature specs, Kanban boards, implementation tickets, or when the user mentions requirements, specs, PRDs, or the docs/requirements directory.
4+
---
5+
6+
# Obsidian Requirements Vault
7+
8+
Manage product and engineering requirements in `docs/requirements/` using feature folders, Kanban boards, and structured tickets designed for AI agent workflows.
9+
10+
## Vault Location & Structure
11+
12+
```
13+
docs/requirements/
14+
README.md # Vault conventions & index
15+
glossary.md # Shared terminology
16+
Main Board.md # Level 1 Kanban: features/epics
17+
Templates/
18+
feature-requirements.md # Template for new requirement specs
19+
implementation-ticket.md # Template for new tickets
20+
Features/
21+
{feature-name}/ # One folder per feature
22+
requirements.md # The requirement specification
23+
board.md # Level 2 Kanban: implementation tickets
24+
tickets/
25+
{ticket-slug}.md # Individual implementation tickets
26+
```
27+
28+
## Kanban Board Format
29+
30+
Boards use the [mgmeyers/obsidian-kanban](https://github.com/mgmeyers/obsidian-kanban) plugin format: a single markdown file with `kanban-plugin: basic` frontmatter, `## Heading` columns, and `- [ ] [[wikilink]]` cards.
31+
32+
### Main Board (`Main Board.md`)
33+
34+
Tracks features/epics through the requirements lifecycle.
35+
36+
**Columns (in order):** `Backlog` → `In Refinement` → `Ready for Implementation` → `In Progress` → `Done`
37+
38+
Cards are wikilinks to feature requirement docs:
39+
40+
```markdown
41+
- [ ] [[Features/feature-name/requirements|Feature Display Name]] #feature
42+
```
43+
44+
### Feature Board (`Features/{feature}/board.md`)
45+
46+
Tracks implementation tickets for a single feature.
47+
48+
**Columns (in order):** `Todo` → `In Progress` → `In Review` → `Done`
49+
50+
Cards are wikilinks to ticket files:
51+
52+
```markdown
53+
- [ ] [[tickets/ticket-slug|FR-N: Ticket Title]]
54+
```
55+
56+
### Board Update Protocol
57+
58+
To move a card between columns:
59+
60+
1. Read the board file
61+
2. Remove the `- [ ] [[...]]` line from the source column
62+
3. Add it under the target `## Column` heading
63+
4. Write the updated file
64+
65+
To mark a card complete, change `- [ ]` to `- [x]`.
66+
67+
## Creating a New Feature
68+
69+
1. Create directory `docs/requirements/Features/{feature-name}/` with a `tickets/` subdirectory
70+
2. Copy `Templates/feature-requirements.md` to `Features/{feature-name}/requirements.md` and fill it in
71+
3. Create `Features/{feature-name}/board.md` using kanban format with tickets in `Todo`
72+
4. Add a card to `Main Board.md` under the appropriate column
73+
74+
## Creating a New Ticket
75+
76+
1. Copy `Templates/implementation-ticket.md` to `Features/{feature-name}/tickets/{ticket-slug}.md`
77+
2. Fill in frontmatter: `id`, `title`, `type`, `priority`, `parent-feature`, `status`
78+
3. Write the requirement statement using SHALL/MUST language
79+
4. Add testable acceptance criteria as checkboxes
80+
5. Add a card to `Features/{feature-name}/board.md` in the `Todo` column
81+
82+
## Requirement Spec Template
83+
84+
Use `Templates/feature-requirements.md`. Required sections:
85+
86+
1. **Document Control** — owner, status, date
87+
2. **Background and Intent** — why this feature exists
88+
3. **Goals** — what success looks like
89+
4. **Non-goals** — explicit exclusions
90+
5. **Personas** — who uses this and how
91+
6. **Functional Requirements** — `FR-*` prefixed, SHALL/MUST language
92+
7. **Non-functional Requirements** — `NFR-*` prefixed, quantitative where possible
93+
8. **Acceptance Criteria** — `AC-*` prefixed, testable
94+
9. **Open Questions** — unresolved items as checkboxes
95+
10. **Rollout Plan** — phased delivery approach
96+
97+
## Ticket Template
98+
99+
Use `Templates/implementation-ticket.md`. Required sections:
100+
101+
1. **Frontmatter** — id, title, type, priority, parent-feature, status
102+
2. **Requirement** — the specific requirement statement
103+
3. **Acceptance Criteria** — testable checkboxes
104+
4. **Implementation Notes** — filled by implementation agent
105+
5. **Source** — wikilink back to requirement doc + section reference
106+
107+
## Requirement ID Prefixes
108+
109+
| Prefix | Meaning |
110+
|---------|----------------------------------------------|
111+
| `FR-*` | Functional requirement |
112+
| `NFR-*` | Non-functional requirement |
113+
| `AC-*` | Acceptance criteria |
114+
| `PAR-*` | Parity constraint (matching existing behavior)|
115+
116+
## Agent Workflow
117+
118+
### Requirements Agent
119+
120+
1. Read `Main Board.md` → find items in `Backlog`
121+
2. Move card to `In Refinement`
122+
3. Create or update `Features/{feature}/requirements.md` using the template
123+
4. Decompose functional requirements into tickets in `Features/{feature}/tickets/`
124+
5. Create `Features/{feature}/board.md` with all tickets in `Todo`
125+
6. Move master board card to `Ready for Implementation`
126+
127+
### Implementation Agent
128+
129+
1. Read a feature's `board.md` → find items in `Todo`
130+
2. Move card to `In Progress`
131+
3. Read the linked ticket file for requirement + acceptance criteria
132+
4. Implement the change in the codebase
133+
5. Check off acceptance criteria checkboxes in the ticket
134+
6. Move card to `In Review` (or `Done` if self-verified)
135+
136+
## Writing Style
137+
138+
- Start with a **Current State** section when grounded in prototype/implemented behavior
139+
- Be specific and testable — avoid vague language like "should be fast"
140+
- Use SHALL for mandatory requirements, SHOULD for recommended, MAY for optional
141+
- Reference source branches or prototypes when documenting parity constraints
142+
- Cross-reference related docs with relative wikilinks: `[[../feature-name/requirements]]` within `Features/`
143+
144+
## Reviewing Requirements
145+
146+
1. Read `Main Board.md` first for an overview of all features and their state
147+
2. Check for missing sections (Goals, Non-goals, Acceptance Criteria)
148+
3. Verify requirement IDs are unique and sequential within each document
149+
4. Flag vague or untestable requirements
150+
5. Verify each FR has at least one corresponding ticket with acceptance criteria
151+
6. Confirm board state matches ticket frontmatter status

‎docs/requirements/.gitignore‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# ===================
2+
# Obsidian
3+
# ===================
4+
5+
# Workspace files (user-specific, change constantly)
6+
.obsidian/workspace.json
7+
.obsidian/workspace-mobile.json
8+
9+
# Cache
10+
.obsidian/cache/
11+
12+
# Plugin data that's user-specific or contains local paths
13+
.obsidian/plugins/*/data.json
14+
15+
# Sync conflicts
16+
.obsidian/sync-conflicts/
17+
18+
# Mobile-specific
19+
.obsidian/.mobile

‎docs/requirements/.obsidian/app.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"attachmentFolderPath": "Attachments",
3+
"alwaysUpdateLinks": true
4+
}

‎docs/requirements/.obsidian/appearance.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{}

‎docs/requirements/.obsidian/community-plugins.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[
2+
"obsidian-kanban"
3+
]

‎docs/requirements/.obsidian/core-plugins.json‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{
2+
"file-explorer": true,
3+
"global-search": true,
4+
"switcher": true,
5+
"graph": true,
6+
"backlink": true,
7+
"canvas": true,
8+
"outgoing-link": true,
9+
"tag-pane": true,
10+
"footnotes": false,
11+
"properties": true,
12+
"page-preview": true,
13+
"daily-notes": true,
14+
"templates": true,
15+
"note-composer": true,
16+
"command-palette": true,
17+
"slash-command": false,
18+
"editor-status": true,
19+
"bookmarks": true,
20+
"markdown-importer": false,
21+
"zk-prefixer": false,
22+
"random-note": false,
23+
"outline": true,
24+
"word-count": true,
25+
"slides": false,
26+
"audio-recorder": false,
27+
"workspaces": false,
28+
"file-recovery": true,
29+
"publish": false,
30+
"sync": true,
31+
"bases": true,
32+
"webviewer": false
33+
}

‎docs/requirements/.obsidian/plugins/obsidian-kanban/main.js‎

Lines changed: 153 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/requirements/.obsidian/plugins/obsidian-kanban/manifest.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"id": "obsidian-kanban",
3+
"name": "Kanban",
4+
"version": "2.0.51",
5+
"minAppVersion": "1.0.0",
6+
"description": "Create markdown-backed Kanban boards in Obsidian.",
7+
"author": "mgmeyers",
8+
"authorUrl": "https://github.com/mgmeyers/obsidian-kanban",
9+
"helpUrl": "https://publish.obsidian.md/kanban/Obsidian+Kanban+Plugin",
10+
"isDesktopOnly": false
11+
}

‎docs/requirements/.obsidian/plugins/obsidian-kanban/styles.css‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/requirements/.obsidian/templates.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"folder": "Templates"
3+
}

0 commit comments

Comments
 (0)