Align git-tasks with knowledge-backed planning workflows

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.gitignore

@@ -1,3 +1,4 @@
 node_modules/
 *.log
 .DS_Store
+test/evals/git-tasks-workspace/

README.md

@@ -79,23 +79,23 @@ Labels created automatically: `epic`, `sprint`, `user-story`
 
 ### Epics
 ```bash
-git-tasks epic create "Title" [-d <desc>] [-p <points>] [--start <date>] [--end <date>] [-a <user>]
+git-tasks epic create "Title" -d <desc> -p <points> --start <date> --end <date> [-k <wiki/knowledge/file.md>] [-a <user>]
 git-tasks epic list [--state open|closed|all] [--short]
 git-tasks epic show <number> [--comments]
 git-tasks epic update <number> [--title <text>] [--points <n>] [--status open|closed]
 ```
 
 ### Sprints
 ```bash
-git-tasks sprint create "Title" [-e <epic>] [-d <desc>] [-p <points>] [--start <date>] [--end <date>]
+git-tasks sprint create "Title" -e <epic> -d <desc> -p <points> --start <date> --end <date> [-k <wiki/knowledge/file.md>] [-a <user>]
 git-tasks sprint list [--epic <n>] [--state open|closed|all] [--short]
 git-tasks sprint show <number> [--comments]
 git-tasks sprint update <number> [--title <text>] [--status open|closed]
 ```
 
 ### User Stories
 ```bash
-git-tasks story create "Title" [-s <sprint>] [-e <epic>] [-p <points>] [--priority low|medium|high]
+git-tasks story create "Title" -s <sprint> -e <epic> -d <desc> -p <points> --priority low|medium|high [-k <wiki/knowledge/file.md>] [-a <user>]
 git-tasks story list [--sprint <n>] [--epic <n>] [--assignee <user>] [--state open|closed|all] [--short]
 git-tasks story show <number> [--comments]
 git-tasks story update <number> [--status open|in-progress|ready-for-review|closed] [--reviewer <user>]
@@ -109,27 +109,75 @@ git-tasks overview [--depth 1|2|3] [--state open|closed|all]
 
 ### Wiki
 ```bash
-git-tasks wiki init
+git-tasks init
 git-tasks wiki list
-git-tasks wiki show <file>
+git-tasks wiki show inbox/<file>
+git-tasks wiki show knowledge/index
 ```
 
 ## Agent-friendly usage
 
 ```bash
+git-tasks init --owner octocat --reviewer octocat
 git-tasks overview --depth 2
 git-tasks epic list --short
 git-tasks story list --short --sprint 5
-git-tasks story update 42 --status in-progress
+git-tasks story update 42 --status in-progress --knowledge wiki/knowledge/auth-plan.md
 git-tasks story update 42 --status ready-for-review --reviewer octocat
 ```
 
+## AI-native planning granularity
+
+- **Stories** are agent-sized atomic slices: independently executable work that should usually take from a few hours up to one day.
+- **Sprints** are short execution windows and should usually stay within three days.
+- **Epics** are the largest planning bucket and should usually stay within two weeks.
+- `.git-tasks/config.json` can override these defaults with repo-specific `planningHorizons` for agents to read.
+- 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.
+
+## Wiki-first knowledge workflow
+
+- Initialize the repository once with `git-tasks init`.
+- Put inbound human or system inputs in `wiki/inbox/` exactly as they arrive: meeting notes, pasted chats, TODO dumps, transcripts, uploads, or scratch notes.
+- Read `wiki/knowledge/index.md` before opening individual knowledge files so you reuse existing context instead of creating duplicate nodes.
+- Keep `wiki/knowledge/` flat. The semantic kind belongs in frontmatter `type`, not in subdirectories.
+- Use dash-case frontmatter keys for knowledge nodes. A practical minimum is `id`, `type`, `title`, `timestamp`, `status`, `tags`, `sources`, `issue-refs`, `neighbours`, and `supersedes`.
+- Knowledge node bodies should capture the context/source, interpretation, planning changes, rationale, and consequences.
+- 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.
+- When backlog items are tied to specific knowledge docs, store repo-relative `wiki/knowledge/...` paths in issue `Knowledge Links` metadata.
+- Legacy `wiki/raw/` and `wiki/processed/` content may still be read for historical context, but new writes should target `wiki/inbox/` and `wiki/knowledge/`.
+
+## Configuration
+
+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.
+
+```json
+{
+  "owner": "octocat",
+  "defaultReviewers": ["octocat"],
+  "planningHorizons": {
+    "storyMaxDays": 1,
+    "sprintMaxDays": 3,
+    "epicMaxWeeks": 2
+  }
+}
+```
+
+- `defaultReviewers` is the repo-level fallback when `--reviewer` is not passed and `GIT_TASKS_REVIEWERS` is not set.
+- `owner` is the last reviewer fallback when `defaultReviewers` is empty.
+- `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.
+
 ## Task lifecycle automation
 
+- New material in `wiki/inbox/` by itself does **not** create or update issues, branches, or pull requests.
+- New or updated knowledge in `wiki/knowledge/` may lead to epic, sprint, or story create/update operations when the planning delta is real.
 - `story update --status in-progress` keeps the story open, updates its workflow status, and ensures a draft PR exists for the current branch.
-- `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`.
+- Agents should pick up stories in an isolated worktree with a named branch and attached draft PR so execution stays reviewable and self-contained.
+- Routine execution should not create new knowledge nodes unless durable understanding or planning changed.
+- `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`.
+- 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.
 - `story update --status closed` closes the story and automatically closes the parent sprint and epic when all of their children are closed.
 - `sprint update --status closed` also cascades closure up to the parent epic when appropriate.
+- Branches and draft PRs are execution artifacts for stories, not wiki entities.
 
 ## Adding a Backend
 

bin/git-tasks.js

@@ -7,6 +7,7 @@ import { makeSprintCommand } from '../src/commands/sprint.js';
 import { makeStoryCommand } from '../src/commands/story.js';
 import { makeOverviewCommand } from '../src/commands/overview.js';
 import { makeSkillCommand } from '../src/commands/skill.js';
+import { makeInitCommand } from '../src/commands/init.js';
 import { makeWikiCommand } from '../src/commands/wiki.js';
 
 const require = createRequire(import.meta.url);
@@ -19,6 +20,7 @@ program
   .description('AI-native GitHub issue planning via epics, sprints, and user stories')
   .version(pkg.version);
 
+program.addCommand(makeInitCommand());
 program.addCommand(makeEpicCommand());
 program.addCommand(makeSprintCommand());
 program.addCommand(makeStoryCommand());

package.json

@@ -9,6 +9,7 @@
   "scripts": {
     "test": "node --test test/cli.test.js",
     "test:coverage": "node --test --experimental-test-coverage test/cli.test.js",
+    "test:evals": "node --test test/evals/eval.js",
     "pack:dry-run": "npm pack --dry-run"
   },
   "files": [

skills/git-tasks/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: git-tasks
-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.
+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.
 allowed-tools: Bash(git-tasks:*), Bash(npx @atena-reply/git-tasks:*)
 hidden: true
 ---
 
 # git-tasks
 
-**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 project plan changes.
+**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.
 
 **Do not use** for one-off issue or PR lookups without project-management intent. For those, use standard `gh` commands:
 ```bash
@@ -21,25 +21,61 @@ gh pr list
 
 - Ensure `gh auth status` succeeds.
 - Prefer `--short` output unless you need full issue bodies or comments.
+- Run `git-tasks init` at the repository root if `wiki/` is missing.
+- 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.
+- If `wiki/knowledge/index.md` exists, read it before opening individual knowledge nodes.
+- 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/`.
+- 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.
 - Start with `git-tasks overview --depth 2` before drilling into individual issues.
 - Install the skill anywhere with `npx @atena-reply/git-tasks skill install --target all`.
 
+## AI-native planning granularity
+
+- **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.
+- **Sprints** should usually span no more than three days.
+- **Epics** should usually span no more than two weeks.
+- If `.git-tasks/config.json` defines `planningHorizons`, treat those values as repo-specific overrides for the default sizing guidance above.
+- Keep dependencies explicit and current: every story should point at its sprint and epic, and every sprint should point at its epic.
+
 ## Recommended workflow
 
-1. Inspect the hierarchy with `git-tasks overview --depth 2`.
-2. Find the right epic with `git-tasks epic list --short`.
-3. Find the right sprint with `git-tasks sprint list --epic <n> --short`.
-4. Inspect or update stories with `git-tasks story list --sprint <n> --short`.
-5. Use `show` only when you need full body text or comments.
+1. Initialize the repository once with `git-tasks init`.
+2. If the user gives you notes in chat or hands you uploaded files, capture the inbound material in `wiki/inbox/` first.
+3. If inbound material is already on disk, treat `wiki/inbox/` as the intake layer and preserve the source wording there.
+4. Read `wiki/knowledge/index.md` before planning so you reuse or refine existing knowledge instead of creating duplicates.
+5. Update or create knowledge nodes in `wiki/knowledge/` only when durable understanding changes.
+6. After the knowledge layer is current, inspect and update epics, sprints, and stories.
+7. Use issue `Knowledge Links` metadata whenever backlog items are tied to specific knowledge docs.
+8. Use `show` only when you need full body text or comments.
+
+Keep `wiki/knowledge/` flat. The semantic kind belongs in frontmatter `type`, not in subdirectories.
+Use dash-case frontmatter keys. A practical minimum is:
+- `id`
+- `type`
+- `title`
+- `timestamp`
+- `status`
+- `tags`
+- `sources`
+- `issue-refs`
+- `neighbours`
+- `supersedes`
+
+Keep the body focused on human-readable reasoning. Each knowledge node should normally include:
+- **Context/Source:** what changed or arrived
+- **Interpretation:** the durable understanding extracted from it
+- **Planning changes:** the backlog changes that should follow, if any
+- **Rationale:** why that decomposition or update is the right one
+- **Consequences:** downstream effects or follow-up implications
 
 ## Core commands
 
 ### Create
 
 ```bash
-git-tasks epic create "Epic title" -d "description" -p 13
-git-tasks sprint create "Sprint title" --epic <n> --start YYYY-MM-DD --end YYYY-MM-DD
-git-tasks story create "Story title" --sprint <n> --epic <n> -p 3 --priority high -a <username>
+git-tasks epic create "Epic title" -d "description" -p 13 --start YYYY-MM-DD --end YYYY-MM-DD --knowledge wiki/knowledge/example.md
+git-tasks sprint create "Sprint title" --epic <n> -d "description" -p 8 --start YYYY-MM-DD --end YYYY-MM-DD --knowledge wiki/knowledge/example.md
+git-tasks story create "Story title" --sprint <n> --epic <n> -d "description" -p 3 --priority high -a <username> --knowledge wiki/knowledge/example.md
 ```
 
 ### Inspect
@@ -56,9 +92,9 @@ git-tasks story show <n>
 ### Update
 
 ```bash
-git-tasks epic update <n> --status closed --points 21
-git-tasks sprint update <n> --status closed
-git-tasks story update <n> --status in-progress
+git-tasks epic update <n> --status closed --knowledge wiki/knowledge/example.md
+git-tasks sprint update <n> --status closed --knowledge wiki/knowledge/example.md
+git-tasks story update <n> --status in-progress --knowledge wiki/knowledge/example.md
 git-tasks story update <n> --status ready-for-review --reviewer octocat
 git-tasks story update <n> --status closed
 git-tasks story update <n> -a <username>
@@ -67,9 +103,10 @@ git-tasks story update <n> -a <username>
 ### Wiki
 
 ```bash
-git-tasks wiki init
+git-tasks init
 git-tasks wiki list
-git-tasks wiki show <filename>
+git-tasks wiki show inbox/<filename>
+git-tasks wiki show knowledge/index
 ```
 
 ## Title conventions
@@ -78,9 +115,17 @@ git-tasks wiki show <filename>
 - Sprint: `sprint(#<epic-number>): <title>`
 - User story: `story(#<sprint-number>): <title>`
 
-## Output guidance
+## Lifecycle boundaries and output guidance
 
-- Use `overview` for context.
-- Use `list --short` for low-token discovery.
+- Read `wiki/knowledge/index.md` first, then open only the relevant knowledge files.
+- New material in `wiki/inbox/` by itself does **not** justify creating or updating issues, branches, or pull requests.
+- New or updated knowledge that changes the plan **may** justify epic/sprint/story create or update operations.
+- Use `overview` for context and `list --short` for low-token discovery.
 - Use `show --comments` only when comments matter.
 - Reuse returned issue numbers as stable references.
+- 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`.
+- When a story is picked up, work from an isolated worktree with a named branch and attached draft PR.
+- Routine execution should follow the existing story lifecycle; do not create new knowledge nodes unless durable understanding or planning changed.
+- 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`.
+- Branches and draft PRs are execution artifacts for stories, not wiki entities.
+- 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.