You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
git-tasks story update 42 --status in-progress --knowledge wiki/knowledge/auth-plan.md
124
126
git-tasks story update 42 --status ready-for-review --reviewer octocat
125
127
```
126
128
129
+
## AI-native planning granularity
130
+
131
+
-**Stories** are agent-sized atomic slices: independently executable work that should usually take from a few hours up to one day.
132
+
-**Sprints** are short execution windows and should usually stay within three days.
133
+
-**Epics** are the largest planning bucket and should usually stay within two weeks.
134
+
-`.git-tasks/config.json` can override these defaults with repo-specific `planningHorizons` for agents to read.
135
+
- Always keep dependencies explicit: stories belong to a sprint and epic, sprints belong to an epic, and each item should carry enough metadata to be auditable without extra chat context.
136
+
137
+
## Wiki-first knowledge workflow
138
+
139
+
- Initialize the repository once with `git-tasks init`.
140
+
- Put inbound human or system inputs in `wiki/inbox/` exactly as they arrive: meeting notes, pasted chats, TODO dumps, transcripts, uploads, or scratch notes.
141
+
- Read `wiki/knowledge/index.md` before opening individual knowledge files so you reuse existing context instead of creating duplicate nodes.
142
+
- Keep `wiki/knowledge/` flat. The semantic kind belongs in frontmatter `type`, not in subdirectories.
143
+
- Use dash-case frontmatter keys for knowledge nodes. A practical minimum is `id`, `type`, `title`, `timestamp`, `status`, `tags`, `sources`, `issue-refs`, `neighbours`, and `supersedes`.
144
+
- Knowledge node bodies should capture the context/source, interpretation, planning changes, rationale, and consequences.
145
+
- Update or create knowledge nodes only when durable understanding changes. Then update epics, sprints, and stories from that compiled knowledge when the plan actually changed.
146
+
- When backlog items are tied to specific knowledge docs, store repo-relative `wiki/knowledge/...` paths in issue `Knowledge Links` metadata.
147
+
- Legacy `wiki/raw/` and `wiki/processed/` content may still be read for historical context, but new writes should target `wiki/inbox/` and `wiki/knowledge/`.
148
+
149
+
## Configuration
150
+
151
+
Run `git-tasks init --owner <user> --reviewer <user>` to create `.git-tasks/config.json` at the repository root. Commit this file so human teammates and AI agents share the same defaults.
152
+
153
+
```json
154
+
{
155
+
"owner": "octocat",
156
+
"defaultReviewers": ["octocat"],
157
+
"planningHorizons": {
158
+
"storyMaxDays": 1,
159
+
"sprintMaxDays": 3,
160
+
"epicMaxWeeks": 2
161
+
}
162
+
}
163
+
```
164
+
165
+
-`defaultReviewers` is the repo-level fallback when `--reviewer` is not passed and `GIT_TASKS_REVIEWERS` is not set.
166
+
-`owner` is the last reviewer fallback when `defaultReviewers` is empty.
167
+
-`planningHorizons` is for AI guidance, not CLI enforcement. It lets each repo tighten or relax the default story/sprint/epic sizing without editing the shipped skill text.
168
+
127
169
## Task lifecycle automation
128
170
171
+
- New material in `wiki/inbox/` by itself does **not** create or update issues, branches, or pull requests.
172
+
- New or updated knowledge in `wiki/knowledge/` may lead to epic, sprint, or story create/update operations when the planning delta is real.
129
173
-`story update --status in-progress` keeps the story open, updates its workflow status, and ensures a draft PR exists for the current branch.
130
-
-`story update --status ready-for-review` promotes the linked draft PR to ready for review and can request reviewers via `--reviewer` or `GIT_TASKS_REVIEWERS=user1,user2`.
174
+
- Agents should pick up stories in an isolated worktree with a named branch and attached draft PR so execution stays reviewable and self-contained.
175
+
- Routine execution should not create new knowledge nodes unless durable understanding or planning changed.
176
+
-`story update --status ready-for-review` promotes the linked draft PR to ready for review and requires reviewers via `--reviewer`, `GIT_TASKS_REVIEWERS=user1,user2`, or the repo-level defaults in `.git-tasks/config.json`.
177
+
- When a story is tied to knowledge docs, surface those docs via issue `Knowledge Links` metadata and in the story PR body for reviewer context.
131
178
-`story update --status closed` closes the story and automatically closes the parent sprint and epic when all of their children are closed.
132
179
-`sprint update --status closed` also cascades closure up to the parent epic when appropriate.
180
+
- Branches and draft PRs are execution artifacts for stories, not wiki entities.
description: AI-native project management CLI for GitHub. Use when the user wants to inspect or update the planning hierarchy (epics, sprints, user stories), drive story lifecycle transitions (start work, ready for review, close), or integrate raw inputs such as client meeting notes or feature transcripts into the existing plan — either by updating open items or creating new ones as a diff. Do not use for reading a single issue or PR without any project-management intent; prefer standard gh commands for those one-off lookups. Triggers include "what's the current sprint status", "create a story for this feature", "move this story to in-progress", "close out the sprint", "update the plan based on today's meeting notes", or any request involving epics, sprints, or story lifecycle management.
3
+
description: AI-native project management CLI for GitHub. Use when the user wants to inspect or update the planning hierarchy (epics, sprints, user stories), drive story lifecycle transitions (start work, ready for review, close), or compile inbound notes, transcripts, uploads, and feature requests into structured wiki knowledge before changing the plan. Do not use for reading a single issue or PR without project-management intent; prefer standard gh commands for those one-off lookups. Triggers include "what's the current sprint status", "create a story for this feature", "move this story to in-progress", "close out the sprint", "update the plan based on today's meeting notes", or any request involving epics, sprints, story lifecycle, or wiki-backed planning updates.
**Use when** you are acting as an AI project manager — inspecting or updating epics, sprints, and user stories, driving story lifecycle transitions, or translating raw inputs (meeting notes, feature requests, transcripts) into structured projectplan changes.
10
+
**Use when** you are acting as an AI project manager — inspecting or updating epics, sprints, and user stories, driving story lifecycle transitions, or translating inbound inputs (meeting notes, feature requests, transcripts, uploaded files) into structured project-plan changes.
11
11
12
12
**Do not use** for one-off issue or PR lookups without project-management intent. For those, use standard `gh` commands:
13
13
```bash
@@ -21,25 +21,61 @@ gh pr list
21
21
22
22
- Ensure `gh auth status` succeeds.
23
23
- Prefer `--short` output unless you need full issue bodies or comments.
24
+
- Run `git-tasks init` at the repository root if `wiki/` is missing.
25
+
- If `.git-tasks/config.json` exists, read it before planning. Use `planningHorizons` as repo-specific sizing guidance and `defaultReviewers` (or `owner`) as the default review handoff target.
26
+
- If `wiki/knowledge/index.md` exists, read it before opening individual knowledge nodes.
27
+
- If the repo still has legacy `wiki/raw/` or `wiki/processed/` content, it is fine to read it for historical context, but write new material into `wiki/inbox/` and `wiki/knowledge/`.
28
+
- If the repo is being initialized for the first time, prefer `git-tasks init --owner <user> --reviewer <user>` so the repo contract is explicit from the start.
24
29
- Start with `git-tasks overview --depth 2` before drilling into individual issues.
25
30
- Install the skill anywhere with `npx @atena-reply/git-tasks skill install --target all`.
26
31
32
+
## AI-native planning granularity
33
+
34
+
-**Stories** are agent-sized atomic units: large enough for one coding agent to finish independently, but usually no more than a few hours to one day.
35
+
-**Sprints** should usually span no more than three days.
36
+
-**Epics** should usually span no more than two weeks.
37
+
- If `.git-tasks/config.json` defines `planningHorizons`, treat those values as repo-specific overrides for the default sizing guidance above.
38
+
- Keep dependencies explicit and current: every story should point at its sprint and epic, and every sprint should point at its epic.
39
+
27
40
## Recommended workflow
28
41
29
-
1. Inspect the hierarchy with `git-tasks overview --depth 2`.
30
-
2. Find the right epic with `git-tasks epic list --short`.
31
-
3. Find the right sprint with `git-tasks sprint list --epic <n> --short`.
32
-
4. Inspect or update stories with `git-tasks story list --sprint <n> --short`.
33
-
5. Use `show` only when you need full body text or comments.
42
+
1. Initialize the repository once with `git-tasks init`.
43
+
2. If the user gives you notes in chat or hands you uploaded files, capture the inbound material in `wiki/inbox/` first.
44
+
3. If inbound material is already on disk, treat `wiki/inbox/` as the intake layer and preserve the source wording there.
45
+
4. Read `wiki/knowledge/index.md` before planning so you reuse or refine existing knowledge instead of creating duplicates.
46
+
5. Update or create knowledge nodes in `wiki/knowledge/` only when durable understanding changes.
47
+
6. After the knowledge layer is current, inspect and update epics, sprints, and stories.
48
+
7. Use issue `Knowledge Links` metadata whenever backlog items are tied to specific knowledge docs.
49
+
8. Use `show` only when you need full body text or comments.
50
+
51
+
Keep `wiki/knowledge/` flat. The semantic kind belongs in frontmatter `type`, not in subdirectories.
52
+
Use dash-case frontmatter keys. A practical minimum is:
53
+
-`id`
54
+
-`type`
55
+
-`title`
56
+
-`timestamp`
57
+
-`status`
58
+
-`tags`
59
+
-`sources`
60
+
-`issue-refs`
61
+
-`neighbours`
62
+
-`supersedes`
63
+
64
+
Keep the body focused on human-readable reasoning. Each knowledge node should normally include:
65
+
-**Context/Source:** what changed or arrived
66
+
-**Interpretation:** the durable understanding extracted from it
67
+
-**Planning changes:** the backlog changes that should follow, if any
68
+
-**Rationale:** why that decomposition or update is the right one
69
+
-**Consequences:** downstream effects or follow-up implications
git-tasks story update <n> --status in-progress --knowledge wiki/knowledge/example.md
62
98
git-tasks story update <n> --status ready-for-review --reviewer octocat
63
99
git-tasks story update <n> --status closed
64
100
git-tasks story update <n> -a <username>
@@ -67,9 +103,10 @@ git-tasks story update <n> -a <username>
67
103
### Wiki
68
104
69
105
```bash
70
-
git-tasks wiki init
106
+
git-tasks init
71
107
git-tasks wiki list
72
-
git-tasks wiki show <filename>
108
+
git-tasks wiki show inbox/<filename>
109
+
git-tasks wiki show knowledge/index
73
110
```
74
111
75
112
## Title conventions
@@ -78,9 +115,17 @@ git-tasks wiki show <filename>
78
115
- Sprint: `sprint(#<epic-number>): <title>`
79
116
- User story: `story(#<sprint-number>): <title>`
80
117
81
-
## Output guidance
118
+
## Lifecycle boundaries and output guidance
82
119
83
-
- Use `overview` for context.
84
-
- Use `list --short` for low-token discovery.
120
+
- Read `wiki/knowledge/index.md` first, then open only the relevant knowledge files.
121
+
- New material in `wiki/inbox/` by itself does **not** justify creating or updating issues, branches, or pull requests.
122
+
- New or updated knowledge that changes the plan **may** justify epic/sprint/story create or update operations.
123
+
- Use `overview` for context and `list --short` for low-token discovery.
85
124
- Use `show --comments` only when comments matter.
86
125
- Reuse returned issue numbers as stable references.
126
+
- When backlog items are tied to knowledge docs, record those links in issue `Knowledge Links` metadata and mirror the issue numbers back into knowledge frontmatter `issue-refs`.
127
+
- When a story is picked up, work from an isolated worktree with a named branch and attached draft PR.
128
+
- Routine execution should follow the existing story lifecycle; do not create new knowledge nodes unless durable understanding or planning changed.
129
+
- When moving a story to `ready-for-review`, make sure the draft PR is promoted and review is requested from `--reviewer` when explicitly provided, otherwise `GIT_TASKS_REVIEWERS`, otherwise `.git-tasks/config.json``defaultReviewers`, falling back to `owner`.
130
+
- Branches and draft PRs are execution artifacts for stories, not wiki entities.
131
+
- Treat worktrees, PR logs, and review handoff as required operating discipline even when your host does not automate them yet; if your agent host supports hooks, that is the right layer to enforce them.
0 commit comments