diff --git a/.claude/hooks/check-version-bump.sh b/.claude/hooks/check-version-bump.sh deleted file mode 100644 index b384872d..00000000 --- a/.claude/hooks/check-version-bump.sh +++ /dev/null @@ -1,50 +0,0 @@ -#!/usr/bin/env bash -# PreToolUse hook: blocks "gh pr create" if version.properties hasn't changed vs main. -# Receives tool input JSON on stdin. - -INPUT=$(cat) - -# Extract command field using python3 (pipe via stdin to avoid quoting issues) -COMMAND=$(echo "$INPUT" | python3 -c " -import json, sys -try: - data = json.loads(sys.stdin.read()) - print(data.get('tool_input', {}).get('command', '')) -except Exception: - print('') -" 2>/dev/null) - -# If extraction failed or command doesn't contain 'gh pr create', allow -if [ -z "$COMMAND" ]; then - exit 0 -fi - -# Match 'gh pr create' only as a shell command (not embedded in strings/commit messages). -# Valid prefixes: start of line, &&, ;, |, or whitespace after those. -if ! echo "$COMMAND" | grep -qE '(^|[;&|]|[[:space:]])\s*gh\s+pr\s+create'; then - exit 0 -fi - -# Command contains 'gh pr create' — find the repo root via git -REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) -if [ $? -ne 0 ] || [ -z "$REPO_ROOT" ]; then - exit 0 -fi - -# Check if version.properties changed vs main -DIFF_OUTPUT=$(git -C "$REPO_ROOT" diff main -- version.properties 2>/dev/null) -GIT_EXIT=$? - -# If git diff failed (e.g. no main branch), allow -if [ $GIT_EXIT -ne 0 ]; then - exit 0 -fi - -# If diff is empty, version.properties hasn't changed — block -if [ -z "$DIFF_OUTPUT" ]; then - printf '{"decision":"block","reason":"version.properties has not been updated. Run /bump-version to analyze the changes, infer the version bump, draft the changelog, and create the PR."}\n' - exit 0 -fi - -# Diff is non-empty — version was bumped, allow -exit 0 diff --git a/.claude/settings.json b/.claude/settings.json index ac9d2d7d..c72c6b73 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,16 +1,3 @@ { - "enabledPlugins": {}, - "hooks": { - "PreToolUse": [ - { - "matcher": "Bash", - "hooks": [ - { - "type": "command", - "command": "bash .claude/hooks/check-version-bump.sh" - } - ] - } - ] - } + "enabledPlugins": {} } diff --git a/.claude/skills/bump-version.md b/.claude/skills/bump-version.md deleted file mode 100644 index 861f4c34..00000000 --- a/.claude/skills/bump-version.md +++ /dev/null @@ -1,270 +0,0 @@ ---- -description: Prepare a release PR by inferring semver bump, drafting a user-facing changelog, and creating the PR via GitHub CLI ---- - -# Bump Version - -Prepares a release PR from the current feature branch to `main`. Reads the commit history, -infers the appropriate semver bump, drafts a user-facing changelog section, confirms with the -user, then updates `version.properties`, `CHANGELOG.md`, and creates the PR. - -**Usage:** `/bump-version` - -Run this from a feature branch that is ready to merge. The branch must have commits ahead of `main`. - ---- - -## Step 1 — Read Current Version - -Read `version.properties` from the project root and extract the three components: - -``` -Read version.properties -``` - -Note the current version as `CURRENT = VERSION_MAJOR.VERSION_MINOR.VERSION_PATCH`. - ---- - -## Step 2 — Gather Raw Material - -Run these three commands via Bash: - -```bash -git log main...HEAD --oneline -``` - -```bash -git diff main...HEAD --stat -``` - -```bash -git diff main...HEAD --name-only -``` - -Collect the full output of each. Do not truncate. - ---- - -## Step 3 — Filter and Synthesize (Critical Reasoning Step) - -**This is not a raw dump of commit messages.** Analyze the material and produce a curated, -user-facing summary. - -### 3a. Discard internal-only commits - -Ignore commits that match any of the following — they carry no user-visible information: - -- Subject starts with: `wip`, `WIP`, `checkpoint`, `fixup!`, `chore: rebase`, `Merge branch`, `version bump` -- Commit only touches: `build.gradle.kts`, `gradle/`, `*.properties`, `.gitignore`, `.github/`, - `Dockerfile`, `docker-compose.yml`, `scripts/`, `*.md` files with no API impact -- Subject is a bare file list or CI housekeeping note - -### 3b. Group meaningful changes by theme - -Use only these categories (omit any that have no entries): - -- **Breaking Changes** — removed tool, renamed/removed parameter, incompatible schema change -- **New Features** — new MCP tool, new operation on existing tool, new config option, new query parameter -- **Bug Fixes** — incorrect behavior corrected, crash fixed, data integrity issue resolved -- **Performance** — measurable throughput or latency improvement -- **Documentation** — user-visible docs, changelog entries (only if substantive) - -### 3c. Write 3–8 user-facing bullet points - -Rules for each bullet: -- Start with a past-tense verb (Added, Fixed, Improved, Removed, Changed) -- Name the tool or feature affected (e.g., `query_container`, `request_transition`) -- Describe the **benefit to the user**, not the implementation detail -- Do not mention internal class names, Kotlin types, or file paths -- Example: `Added \`includeAncestors\` parameter to \`query_items\` — eliminates parent-walk call chains for breadcrumb context` - ---- - -## Step 4 — Infer Bump Level - -Examine the synthesized changes and determine the bump level using this decision tree: - -| Condition | Bump | -|-----------|------| -| Any breaking API change (removed tool, renamed/removed required parameter, incompatible response schema) | **major** | -| New tool added, new capability on existing tool, new config option, new query parameter | **minor** | -| Bug fix, performance improvement, docs only, internal refactor with no API change | **patch** | - -If multiple conditions apply, use the highest applicable level. - -State the bump level and the one-sentence reason. For example: -> Bump: **minor** — `includeAncestors` parameter added to three read tools (new capability, no breaking change). - -Calculate the proposed new version: -- **patch**: increment `VERSION_PATCH` by 1, keep others -- **minor**: increment `VERSION_MINOR` by 1, reset `VERSION_PATCH` to 0, keep `VERSION_MAJOR` -- **major**: increment `VERSION_MAJOR` by 1, reset `VERSION_MINOR` and `VERSION_PATCH` to 0 - ---- - -## Step 5 — Present for Confirmation - -Output the following block and **stop**. Wait for the user to confirm or request changes before -proceeding. - -``` -## Proposed Release: vX.Y.Z (CURRENT → NEW) - -**Bump level:** -**Reason:** - -### Changelog Draft - -## [X.Y.Z] - YYYY-MM-DD - -### -- -- -... - ---- -``` - -Use today's date in `YYYY-MM-DD` format for the changelog header. - -If the user requests changes to the wording or bump level, revise and re-present before -continuing. - ---- - -## Step 6 — Apply Changes (After Confirmation) - -### 6a. Update `version.properties` - -Edit `version.properties` in the project root. Set exactly the lines that need to change. -Reset lower components if performing a major or minor bump. - -Example for a minor bump from 2.0.0 → 2.1.0: -``` -VERSION_MAJOR=2 -VERSION_MINOR=1 -VERSION_PATCH=0 -``` - -### 6b. Insert new section into `CHANGELOG.md` - -Read `CHANGELOG.md`. Find the line of the most recent `## [` entry (the first versioned section -after the header). Insert the new section **immediately above** that line, including the trailing -`---` separator and a blank line: - -```markdown -## [X.Y.Z] - YYYY-MM-DD - -### Added -- bullet 1 -- bullet 2 - ---- - -## [previous version] ... -``` - -Do not modify any existing entries. - -### 6c. Stage both files - -```bash -git add version.properties CHANGELOG.md -``` - -Confirm both files appear as staged (green) in `git status`. Do not stage anything else. - ---- - -## Step 7 — Create the PR - -Construct and run the following command, substituting the actual version and changelog bullets: - -```bash -gh pr create \ - --title "release: vX.Y.Z — " \ - --body "$(cat <<'EOF' -## Summary - -- -- -- - -## Version - - → - -🤖 Prepared with /bump-version -EOF -)" -``` - -The `--title` one-line summary should capture the most user-significant change from the changelog -(not a generic "bump version" message). - -If the branch already has an open PR, run `gh pr edit` with the same title and body instead of -`gh pr create`. - -If the user says "show me the command" or "don't run it yet", print the full command as a code -block instead of executing it. - ---- - -## Step 8 — Pre-PR Checklist - -Before printing the summary, verify these items in the README and fix any that are stale. Do NOT stage extra files — if fixes are needed, include them in the same staged set before the PR is created. - -**README checks (run grep to verify):** - -```bash -grep -n "ghcr.io/jpicklyk/task-orchestrator" README.md -``` - -Every Docker image reference must use `:latest` — never a branch name (`:main`, `:overhaul`, etc.) or a hardcoded version tag. The CI workflow publishes `:latest` on every merge to `main`; pinned semver tags (e.g., `:2.0.1`) are also published but should not appear in the Quick Start instructions. - -**Version badge** (line ~7 in README): - -The badge must use the `shields.io/github/v/tag/` endpoint (not `/release/`) because the CI workflow creates git tags, not GitHub Releases: - -``` -[![Version](https://img.shields.io/github/v/tag/jpicklyk/task-orchestrator?sort=semver)](...) -``` - -The badge auto-updates when CI pushes the `vX.Y.Z` tag after merge — no manual update needed. - -**If fixes are required**, make the edits, then: - -```bash -git add README.md version.properties CHANGELOG.md -``` - -and re-confirm `git status` shows only those three files staged. - ---- - -## Step 9 — Print Summary - -Output a brief summary: - -``` -Version bumped: CURRENT → NEW () -Files staged: version.properties, CHANGELOG.md -PR: -``` - ---- - -## Quick Reference - -| Bump level | When | Version change | -|------------|------|---------------| -| major | Breaking API change | X+1.0.0 | -| minor | New capability, no breaking change | X.Y+1.0 | -| patch | Bug fix, docs, refactor | X.Y.Z+1 | - -**Common mistakes to avoid:** -- Do not include raw commit hashes or internal file paths in the changelog -- Do not bump version without confirmation from the user -- Do not stage files other than `version.properties` and `CHANGELOG.md` -- Do not create the PR if the branch has no commits ahead of `main` diff --git a/.claude/skills/prepare-release.md b/.claude/skills/prepare-release.md new file mode 100644 index 00000000..05dee57c --- /dev/null +++ b/.claude/skills/prepare-release.md @@ -0,0 +1,279 @@ +--- +description: Prepare a versioned release from main — reads commits since last tag, infers semver bump, drafts changelog, creates release branch and PR, then provides the trigger command for Docker publish and GitHub release. +--- + +# Prepare Release + +Prepares a release from the current state of `main`. Reads commits since the last release tag, +infers the semver bump, drafts a user-facing changelog, confirms with you, then creates a +`release/vX.Y.Z` branch, commits the version bump, and opens a PR. After you merge the PR, +one command triggers the Docker build and GitHub release. + +**Usage:** `/prepare-release` + +Run this from any branch after all feature PRs have been merged to `main`. + +--- + +## Step 1 — Ensure Clean Main + +Switch to `main` and pull latest: + +```bash +git checkout main +git pull origin main +git status +``` + +If `git status` shows uncommitted changes, stop and resolve them before continuing. The +working tree must be clean. + +--- + +## Step 2 — Find Last Release Tag + +```bash +git describe --tags --abbrev=0 +``` + +Note this as `LAST_TAG` (e.g., `v2.0.2`). All commits after this tag are candidates for +the release. + +If this command fails (no tags exist yet), use the full history — note the first commit +hash as the baseline and treat the release as the initial version. + +--- + +## Step 3 — Gather Commits Since Last Tag + +```bash +git log ...HEAD --oneline +git diff ...HEAD --stat +git diff ...HEAD --name-only +``` + +Collect the full output of each. Do not truncate. + +--- + +## Step 4 — Filter and Synthesize (Critical Reasoning Step) + +**This is not a raw dump of commit messages.** Analyze the material and produce a curated, +user-facing summary. + +### 4a. Discard internal-only commits + +Ignore commits that match any of the following: + +- Subject starts with: `wip`, `WIP`, `checkpoint`, `fixup!`, `chore: rebase`, + `Merge branch`, `version bump`, `release:` +- Commit only touches: `build.gradle.kts`, `gradle/`, `*.properties`, `.gitignore`, + `.github/`, `Dockerfile`, `docker-compose.yml`, `scripts/`, `*.md` files with no API impact +- Subject is a bare file list or CI housekeeping note + +### 4b. Group meaningful changes by theme + +Use only these categories (omit any that have no entries): + +- **Breaking Changes** — removed tool, renamed/removed parameter, incompatible schema change +- **New Features** — new MCP tool, new operation on existing tool, new config option, new query parameter +- **Bug Fixes** — incorrect behavior corrected, crash fixed, data integrity issue resolved +- **Performance** — measurable throughput or latency improvement +- **Documentation** — user-visible docs (only if substantive) + +### 4c. Write 3–8 user-facing bullet points + +Rules for each bullet: +- Start with a past-tense verb (Added, Fixed, Improved, Removed, Changed) +- Name the tool or feature affected (e.g., `query_items`, `advance_item`) +- Describe the **benefit to the user**, not the implementation detail +- Do not mention internal class names, Kotlin types, or file paths +- Example: `Added \`includeAncestors\` to \`query_items\` — eliminates parent-walk call chains for breadcrumb context` + +--- + +## Step 5 — Infer Bump Level + +Examine the synthesized changes and determine the bump level: + +| Condition | Bump | +|-----------|------| +| Any breaking API change (removed tool, renamed/removed required parameter, incompatible response schema) | **major** | +| New tool, new capability on existing tool, new config option, new query parameter | **minor** | +| Bug fix, performance improvement, docs only, internal refactor with no API change | **patch** | + +If multiple conditions apply, use the highest applicable level. + +State the bump level and the one-sentence reason. Example: +> Bump: **minor** — GitHub wiki CI sync and release automation added (new capability, no breaking change). + +Calculate the proposed new version: +- **patch**: increment `VERSION_PATCH` by 1, keep others +- **minor**: increment `VERSION_MINOR` by 1, reset `VERSION_PATCH` to 0, keep `VERSION_MAJOR` +- **major**: increment `VERSION_MAJOR` by 1, reset `VERSION_MINOR` and `VERSION_PATCH` to 0 + +--- + +## Step 6 — Present for Confirmation + +Output the following block and **stop**. Wait for the user to confirm or request changes. + +``` +## Proposed Release: vX.Y.Z (CURRENT → NEW) + +**Bump level:** +**Reason:** + +### Changelog Draft + +## [X.Y.Z] - YYYY-MM-DD + +### +- +- +... + +--- +``` + +Use today's date in `YYYY-MM-DD` format. If the user requests changes, revise and +re-present before continuing. + +--- + +## Step 7 — Create Release Branch + +After confirmation: + +```bash +git checkout -b release/vX.Y.Z +``` + +--- + +## Step 8 — Apply Changes + +### 8a. Update `version.properties` + +Edit `version.properties` in the project root. Set only the lines that need to change. +Reset lower components on a major or minor bump. + +Example for a minor bump from 2.0.2 → 2.1.0: +``` +VERSION_MAJOR=2 +VERSION_MINOR=1 +VERSION_PATCH=0 +``` + +### 8b. Insert new section into `CHANGELOG.md` + +Read `CHANGELOG.md`. Find the first `## [` versioned entry (after the header). Insert the +new section **immediately above** it, with a trailing `---` separator and a blank line: + +```markdown +## [X.Y.Z] - YYYY-MM-DD + +### Added +- bullet 1 +- bullet 2 + +--- + +## [previous version] ... +``` + +Do not modify any existing entries. + +### 8c. Stage, commit, and push + +```bash +git add version.properties CHANGELOG.md +git status # confirm only these two files are staged +git commit -m "release: bump to vX.Y.Z" +git push origin release/vX.Y.Z +``` + +--- + +## Step 9 — Pre-PR Checklist + +Before creating the PR, verify these README items and fix any that are stale. If fixes are +needed, add `README.md` to the staged files and amend the commit before pushing. + +**Docker image references:** + +```bash +grep -n "ghcr.io/jpicklyk/task-orchestrator" README.md +``` + +Every Docker image reference must use `:latest` — never a branch name or hardcoded version tag. + +**Version badge** (line ~7 in README): + +Both `/github/v/tag/` and `/github/v/release/` badge endpoints work — the CI workflow +creates a git tag and a GitHub release on every deploy. No change needed unless the URL +is broken. + +--- + +## Step 10 — Create the PR + +```bash +gh pr create \ + --base main \ + --title "release: vX.Y.Z — " \ + --body "$(cat <<'EOF' +## Summary + +- +- +- + +## Version + + → + +🤖 Prepared with /prepare-release +EOF +)" +``` + +If the branch already has an open PR, use `gh pr edit` with the same title and body instead. + +If the user says "show me the command" or "don't run it yet", print the full command as a +code block instead of executing it. + +--- + +## Step 11 — Print Summary and Trigger Command + +Output this block after the PR is created: + +``` +Release prepared: CURRENT → vX.Y.Z () +Branch: release/vX.Y.Z +PR: + +After merging the PR, trigger the Docker build and GitHub release: + + gh workflow run docker-publish.yml --ref main + +Or use the Actions tab: + https://github.com/jpicklyk/task-orchestrator/actions/workflows/docker-publish.yml +``` + +--- + +## Quick Reference + +| Bump level | When | Version change | +|------------|------|---------------| +| major | Breaking API change | X+1.0.0 | +| minor | New capability, no breaking change | X.Y+1.0 | +| patch | Bug fix, docs, refactor | X.Y.Z+1 | + +**Common mistakes to avoid:** +- Do not include raw commit hashes or internal file paths in the changelog +- Do not bump version without confirmation from the user +- Do not stage files other than `version.properties`, `CHANGELOG.md` (and `README.md` if fixes were needed) +- Do not create the PR if there are no commits ahead of the last tag diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 40eee3ca..75c41aee 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -1,50 +1,15 @@ -name: Build and Push Docker Image +name: Build, Publish, and Release on: - push: - branches: - - '**' # all branches - pull_request: - branches: [ main ] + workflow_dispatch: env: REGISTRY: ghcr.io IMAGE_NAME: ${{ github.repository }} jobs: - test: - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Set up JDK 23 - uses: actions/setup-java@v4 - with: - java-version: '23' - distribution: 'temurin' - - - name: Setup Gradle - uses: gradle/actions/setup-gradle@v3 - - - name: Make gradlew executable - run: chmod +x gradlew - - - name: Run tests - run: ./gradlew :current:test --no-daemon - - - name: Publish Test Report - uses: mikepenz/action-junit-report@v4 - if: always() - with: - report_paths: '**/build/test-results/test/TEST-*.xml' - check_name: 'Test Results' - build: - needs: test runs-on: ubuntu-latest - if: github.event_name == 'push' permissions: contents: write @@ -81,18 +46,14 @@ jobs: username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - # --- Main branch only: resolve and guard version --- - - name: Get version id: version - if: github.ref == 'refs/heads/main' run: | VERSION=$(./gradlew -q :current:printTagVersion) echo "version=${VERSION}" >> $GITHUB_OUTPUT echo "Building version: ${VERSION}" - name: Check version tag does not exist - if: github.ref == 'refs/heads/main' run: | VERSION=${{ steps.version.outputs.version }} if git ls-remote --tags origin "refs/tags/v${VERSION}" | grep -q "v${VERSION}"; then @@ -101,7 +62,6 @@ jobs: fi - name: Create and push version tag - if: github.ref == 'refs/heads/main' run: | VERSION=${{ steps.version.outputs.version }} git config user.name "github-actions[bot]" @@ -109,11 +69,8 @@ jobs: git tag "v${VERSION}" git push origin "v${VERSION}" - # --- Main branch: semver Docker metadata --- - - - name: Extract metadata (main) - id: meta-main - if: github.ref == 'refs/heads/main' + - name: Extract Docker metadata + id: meta uses: docker/metadata-action@v5 with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} @@ -122,53 +79,28 @@ jobs: type=raw,value=${{ steps.version.outputs.version }} type=semver,pattern={{major}}.{{minor}},value=${{ steps.version.outputs.version }} - # --- Non-main branches: branch-name Docker metadata --- - - - name: Extract metadata (branch) - id: meta-branch - if: github.ref != 'refs/heads/main' - uses: docker/metadata-action@v5 - with: - images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} - tags: | - type=ref,event=branch - - # --- Build and push (main) --- - - - name: Build and push Docker image (main) - if: github.ref == 'refs/heads/main' + - name: Build and push Docker image uses: docker/build-push-action@v5 with: context: . target: runtime-current push: true platforms: linux/amd64,linux/arm64 - tags: ${{ steps.meta-main.outputs.tags }} - labels: ${{ steps.meta-main.outputs.labels }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} cache-from: type=gha cache-to: type=gha,mode=max - # --- Build and push (non-main) --- - - - name: Build and push Docker image (branch) - if: github.ref != 'refs/heads/main' + - name: Create GitHub Release env: - CI_BUILD_NUMBER: ${{ github.run_number }} - uses: docker/build-push-action@v5 - with: - context: . - target: runtime-current - push: true - platforms: linux/amd64,linux/arm64 - tags: ${{ steps.meta-branch.outputs.tags }} - labels: ${{ steps.meta-branch.outputs.labels }} - cache-from: type=gha - cache-to: type=gha,mode=max - - # --- Trivy: main only --- + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh release create "v${{ steps.version.outputs.version }}" \ + --title "v${{ steps.version.outputs.version }}" \ + --generate-notes \ + --verify-tag - name: Run Trivy vulnerability scanner - if: github.ref == 'refs/heads/main' uses: aquasecurity/trivy-action@master with: image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }} diff --git a/.github/workflows/sync-wiki.yml b/.github/workflows/sync-wiki.yml new file mode 100644 index 00000000..2522cedd --- /dev/null +++ b/.github/workflows/sync-wiki.yml @@ -0,0 +1,46 @@ +name: Sync Docs to Wiki + +on: + push: + branches: + - main + paths: + - 'current/docs/**' + workflow_dispatch: + +permissions: + contents: write + +jobs: + sync-wiki: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Clone wiki repository + run: | + git clone "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.wiki.git" wiki-repo + + - name: Copy docs to wiki + run: | + cp current/docs/*.md wiki-repo/ + + - name: Configure git identity + working-directory: wiki-repo + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + - name: Commit and push changes + working-directory: wiki-repo + run: | + git add . + if git diff --cached --quiet; then + echo "No changes to sync." + else + git commit -m "docs: sync from main (${{ github.sha }})" + git push + fi diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index f4805651..b0f111ec 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,9 +1,9 @@ name: Run Tests on: - pull_request: - branches: [ main ] push: + branches: ['**'] + pull_request: branches: [ main ] jobs: @@ -29,7 +29,7 @@ jobs: run: chmod +x gradlew - name: Run tests - run: ./gradlew test --no-daemon --tests '*' --tests '!DescriptionFieldMigrationTest' + run: ./gradlew :current:test --no-daemon - name: Publish Test Report uses: mikepenz/action-junit-report@v4 diff --git a/README.md b/README.md index a73ae3a0..1753327b 100644 --- a/README.md +++ b/README.md @@ -286,6 +286,7 @@ v3 exposes **13 tools** organized around the WorkItem graph: ## Documentation +- **[Wiki](https://github.com/jpicklyk/task-orchestrator/wiki)** — Full documentation hub - **[Quick Start Guide](current/docs/quick-start.md)** — Setup walkthrough and first work item - **[API Reference](current/docs/api-reference.md)** — All 13 MCP tools, parameters, and response shapes - **[Workflow Guide](current/docs/workflow-guide.md)** — Note schemas, phase gates, dependency patterns, and lifecycle examples diff --git a/current/docs/Home.md b/current/docs/Home.md new file mode 100644 index 00000000..732c6a37 --- /dev/null +++ b/current/docs/Home.md @@ -0,0 +1,53 @@ +# MCP Task Orchestrator + +Stop losing context. Start building faster. + +MCP Task Orchestrator is an open-source MCP server that gives AI agents persistent, structured task tracking across sessions. Built around a unified WorkItem graph with Note attachments and Dependency edges, it keeps context lean while making complex project work visible. v3 is a ground-up rewrite with 13 tools, role-based workflow, and note schema gating. + +--- + +## What's New in v3 + +- Unified WorkItem model — one entity type at flexible depth (0-3), replacing separate Project/Feature/Task distinctions +- 13 tools with graph-aware queries (`includeAncestors`, `includeChildren`) that eliminate sequential parent-walk calls +- Role-based workflow: `queue` -> `work` -> `review` -> `terminal` with named triggers (`start`, `complete`, `block`, `hold`, `resume`) +- Note schemas — per-tag documentation requirements that gate phase transitions before an item can advance +- Dependency patterns: `linear`, `fan-out`, `fan-in` with `BLOCKS`, `IS_BLOCKED_BY`, and `RELATES_TO` edge types +- `create_work_tree` for atomic hierarchy creation; `complete_tree` for batch topological completion + +--- + +## Quick Install + +Run this once in your terminal to register the server with Claude Code: + +```bash +claude mcp add-json mcp-task-orchestrator '{ + "command": "docker", + "args": [ + "run", "--rm", "-i", + "-v", "mcp-task-data:/app/data", + "ghcr.io/jpicklyk/task-orchestrator:latest" + ] +}' +``` + +After running, restart Claude Code and run `/mcp` to verify the connection. You should see `mcp-task-orchestrator` listed as connected with all 13 tools available. + +--- + +## Documentation + +| Guide | Description | +|-------|-------------| +| [Quick Start](quick-start) | Docker setup, first work item, note schemas, key concepts | +| [API Reference](api-reference) | All 13 MCP tools — parameters, response shapes, and examples | +| [Workflow Guide](workflow-guide) | Role lifecycle, triggers, note schemas, dependency patterns, cascade behavior | + +--- + +## Links + +- [GitHub Repository](https://github.com/jpicklyk/task-orchestrator) +- [Container Registry (ghcr.io)](https://github.com/jpicklyk/task-orchestrator/pkgs/container/task-orchestrator) +- [Changelog](https://github.com/jpicklyk/task-orchestrator/blob/main/CHANGELOG.md) diff --git a/current/docs/_Sidebar.md b/current/docs/_Sidebar.md new file mode 100644 index 00000000..ec2455ac --- /dev/null +++ b/current/docs/_Sidebar.md @@ -0,0 +1,14 @@ +## Navigation + +**Getting Started** +- [Home](Home) +- [Quick Start](quick-start) + +**Reference** +- [API Reference](api-reference) +- [Workflow Guide](workflow-guide) + +**Project** +- [GitHub Repository](https://github.com/jpicklyk/task-orchestrator) +- [Container Registry](https://github.com/jpicklyk/task-orchestrator/pkgs/container/task-orchestrator) +- [Changelog](https://github.com/jpicklyk/task-orchestrator/blob/main/CHANGELOG.md)