taip-connect 0.5.0

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "taip-connect",
+  "version": "0.5.0",
+  "description": "taip-connect — wire the hosted taip brain + context + taip-tools MCP servers into Claude Code (VS Code).",
+  "bin": {
+    "taip-connect": "bin/connect.js"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "packs/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED",
+  "repository": "github:taip-ai/taip-agent"
+}

package/packs/process/skills/taip-workflow-acceptance-testing/SKILL.md

@@ -0,0 +1,159 @@
+---
+id: process/skills/taip-workflow-acceptance-testing
+version: 1.0.1
+trigger: "acceptance testing|run AT|acceptance test|sign off|ready for done|hotfix AT"
+description: >
+  Runs acceptance testing against a plan's acceptance criteria or a PM tool's ticket list.
+  Walks each Given-When-Then AC, records Pass/Fail/Blocked, generates an AT report,
+  writes it to docs/tests/, updates the traceability matrix, and gates completion on sign-off.
+  If a PM tool binding (Plane/Jira) is active, also posts the report as a ticket comment
+  and gates the tool's "Done" transition. Works offline with no PM tool.
+user-invocable: true
+tags: [acceptance-testing, qa, verification, process]
+attribution:
+  source: original
+  license: brain-official
+  author: brain Official
+---
+
+# taip-workflow-acceptance-testing
+
+Acceptance testing gate: load ACs → walk each → record results → write report → update traceability → gate sign-off.
+
+---
+
+## Step 1 — Determine scope
+
+Ask in one message if not already provided:
+
+1. **Scope:** Plan file path (e.g. `docs/plans/2026-06-12-slug.md`) OR ticket key(s) if a PM tool is active
+2. **Hotfix?** Yes / No — if yes, all ACs must pass before going live
+
+---
+
+## Step 2 — Load acceptance criteria
+
+**Path A — from plan file (default, no tool needed):**
+
+1. Read the plan file's `## Acceptance Tests` table
+2. If the table is empty or has no rows with `Given/When/Then`: stop and tell the user:
+   > "No acceptance criteria found in `## Acceptance Tests`. Please add Given/When/Then rows before running AT."
+3. Also load any linked `docs/tests/<slug>-acceptance.md` for full test case scenarios
+
+**Path B — from PM tool (if active):**
+
+1. Fetch tickets in `Acceptance Testing` or `System Testing` state for the scope
+2. Parse each ticket's `## Acceptance Criteria` section for Given/When/Then lines
+3. If a ticket has no `## Acceptance Criteria`: skip it and warn the user
+
+---
+
+## Step 3 — Walk each AC and record result
+
+For each AC, display:
+
+```
+───────────────────────────────────
+AC{N}: Given {precondition}, when {action}, then {expected outcome}.
+───────────────────────────────────
+Result? [Pass / Fail / Blocked]   Notes (optional):
+```
+
+WAIT for the user's result before moving to the next AC.
+
+Build a results table:
+
+| AC | Criterion (short) | Result | Notes |
+|---|---|---|---|
+| AC1 | Given … then … | ✅ Pass | — |
+| AC2 | Given … then … | ❌ Fail | {notes} |
+
+**Overall verdict:**
+- **PASS** — all ACs pass
+- **FAIL** — one or more ACs fail or are blocked
+
+MUST NOT skip or estimate AC results — every AC must be explicitly recorded.
+
+---
+
+## Step 4 — Generate AT report
+
+**Report filename:** `docs/tests/AT-<DDMMYYYY>-<scope-slug>.md`
+
+Get today's date: `date +%d%m%Y`
+
+**Report template:**
+
+```markdown
+# Acceptance Test Report — {scope}
+
+**Date:** {DD Month YYYY}
+**Tester:** {user name}
+**Type:** {Regular / Hotfix}
+**Scope:** {plan file or ticket keys}
+
+## Summary
+
+| Metric | Value |
+|---|---|
+| ACs tested | {N} |
+| PASS | {N} |
+| FAIL | {N} |
+| Overall verdict | ✅ ALL PASS / ❌ FAILURES PRESENT |
+
+{If hotfix:}
+> ⚠ **Hotfix** — all ACs MUST pass. Live release: {BLOCKED / APPROVED}.
+
+## Results
+
+| AC | Criterion | Result | Notes |
+|---|---|---|---|
+| AC1 | Given … then … | ✅ Pass | — |
+
+## Sign-off
+
+- [ ] Sign-off: _____________________ Date: ___________
+```
+
+Write the report to `docs/tests/AT-<DDMMYYYY>-<scope-slug>.md`.
+
+---
+
+## Step 5 — Update traceability matrix
+
+Update `docs/traceability-matrix.md`:
+- Add or update the row(s) linking the plan → this AT report
+- Format: `[AT-DDMMYYYY-scope](tests/AT-DDMMYYYY-scope.md)`
+
+If `docs/traceability-matrix.md` does not exist: create it from the traceability matrix template.
+
+---
+
+## Step 6 — PM tool sync (only if a tool binding is active)
+
+**If Plane or Jira is configured:**
+
+For each ticket in scope:
+1. Post the AT report as a comment on the ticket
+2. Comment MUST include: report link, overall verdict, AC table, next step
+
+**If PASS:** ask "Has the tester/QM signed off on {ticket}? (Y/N)"
+- Yes → transition ticket to **Done**
+- No → print "Waiting for sign-off. Transition manually when approved."
+
+**If FAIL:** do NOT transition. Print:
+> "❌ {ticket} — FAIL. Return to developer. Ticket stays in Acceptance Testing."
+
+**If no PM tool:** skip this step. Sign-off is recorded in the report file and traceability matrix.
+
+---
+
+## Hard fails
+
+- MUST NOT mark a task complete without writing the AT report to `docs/tests/`
+- MUST NOT mark a task complete without updating `docs/traceability-matrix.md`
+- MUST NOT skip or estimate any AC — record every one as Pass / Fail / Blocked
+- MUST NOT transition a PM ticket to Done if any AC is Fail or Blocked
+- MUST NOT transition a PM ticket to Done without explicit sign-off confirmation from user
+- MUST NOT transition a PM ticket to Done without posting a comment first (if tool active)
+- For hotfix: MUST print live release BLOCKED message if any AC failed

package/packs/process/skills/taip-workflow-git-init/SKILL.md

@@ -0,0 +1,131 @@
+---
+id: process/git/git-init
+version: 1.1.0
+trigger: "init git|setup git|initialize repo|git setup|setup branches|init branches"
+description: >
+  Bootstraps a repo with the main/develop branch model. Checks pre-conditions,
+  creates develop from main if missing, pushes both branches to the remote,
+  emits a CLAUDE.md snippet, and optionally sets GitHub branch protection.
+user-invocable: true
+tags: [git, branching, workflow, init]
+attribution:
+  source: original
+  license: brain-official
+  author: brain Official
+---
+
+# taip-workflow-git-init
+
+Set up the main/develop branch model in a repo. Run once on a new repo or to
+align an existing repo to the strategy defined in `process/git/branch-strategy`.
+
+## Pre-conditions
+
+**Check 1 — Git repo:**
+```bash
+git rev-parse --git-dir
+```
+If not a git repo: stop and tell the user to run `git init` first.
+
+**Check 2 — At least one commit:**
+```bash
+git log --oneline -1
+```
+If empty repo: stop and tell the user to make an initial commit first.
+
+**Check 3 — Remote configured (info only):**
+```bash
+git remote -v
+```
+If no remote: warn that branches will be created locally only. Continue.
+
+**Check 4 — Current branch:**
+Note the current branch name. If it is `master`, ask: "This repo uses `master`. Rename
+to `main`? (Y / keep master)" — proceed based on answer. If it is already `main`, continue.
+
+## Step 1 — Ensure main exists
+
+If current branch is `master` and user confirmed rename:
+```bash
+git branch -m master main
+git push origin main --force-with-lease   # only if a remote is configured
+git push origin --delete master           # only if remote master exists
+```
+
+If current branch is already `main` or another name: skip.
+
+## Step 2 — Create develop
+
+Check if `develop` already exists:
+```bash
+git branch --list develop
+git branch -r --list origin/develop
+```
+
+If `develop` does not exist locally:
+```bash
+git checkout -b develop
+git checkout -        # return to previous branch
+```
+
+If `develop` already exists locally: skip creation, report "develop already exists".
+
+## Step 3 — Push both branches to remote
+
+Only if a remote is configured:
+```bash
+git push -u origin main
+git push -u origin develop
+```
+
+If push fails due to no remote: skip silently (already warned in pre-conditions).
+
+## Step 4 — Emit CLAUDE.md snippet
+
+Output this block to stdout so the user can paste it into their project's CLAUDE.md:
+
+```
+## Branch model
+
+| Branch | Role |
+|---|---|
+| `main` | Production-stable — receives merges from `develop` at release time |
+| `develop` | Integration branch — all feature and fix PRs target this |
+| `feature/{slug}-{sequence_id}` | Task branches (from Plane issues) |
+| `fix/{slug}` | Hotfix branches |
+
+PRs: feature/* and fix/* → develop. develop → main at release only.
+```
+
+## Step 5 — Optional GitHub branch protection (if GitHub remote detected)
+
+Check for GitHub remote:
+```bash
+git remote get-url origin | grep github.com
+```
+
+If GitHub remote found, ask: "Configure branch protection for main and develop via gh CLI? (Y / n)"
+
+On Y:
+```bash
+gh api repos/{owner}/{repo}/branches/main/protection \
+  --method PUT \
+  --input - <<'EOF'
+{"required_status_checks":null,"enforce_admins":false,"required_pull_request_reviews":{"required_approving_review_count":0},"restrictions":null}
+EOF
+
+gh api repos/{owner}/{repo}/branches/develop/protection \
+  --method PUT \
+  --input - <<'EOF'
+{"required_status_checks":null,"enforce_admins":false,"required_pull_request_reviews":{"required_approving_review_count":0},"restrictions":null}
+EOF
+```
+
+Report success or any error from the API.
+
+## Rules
+
+- MUST NOT force-push `main` unless the user explicitly confirmed the `master` → `main` rename
+- MUST NOT delete any remote branch without explicit user confirmation
+- MUST report clearly what was created vs what already existed (idempotent output)
+- If `develop` already exists: skip creation silently and confirm it's on the remote

package/packs/process/skills/taip-workflow-git-pr/SKILL.md

@@ -0,0 +1,113 @@
+---
+id: process/git/pr-creation
+version: 1.1.0
+trigger: "create pr|make pr|open pull request|submit pr|raise pr"
+description: >
+  Creates a pull request with pre-flight checks. Verifies branch state, generates
+  a conventional PR title and description, references the plan file if one exists,
+  and outputs the PR link. Use when user says "create a PR", "open a pull request",
+  or "submit my changes".
+user-invocable: true
+tags: [git, pr, workflow]
+attribution:
+  source: original
+  license: brain-official
+  author: brain Official
+---
+
+# taip-workflow-git-pr
+
+PR creation: pre-flight → draft PR → confirm → create.
+
+## Pre-conditions
+
+**Check 1 — Not on main/master/develop:**
+Verify current branch is NOT `main`, `master`, or `develop`. If it is: stop and ask the user to switch to a feature or fix branch.
+
+**Check 2 — Uncommitted changes:**
+If `git status` shows uncommitted changes: stop and ask the user to commit or stash first.
+
+**Check 3 — CI status:**
+Check if CI is passing on the current branch. Warn if CI status cannot be determined.
+
+## Step 1 — Gather info
+
+Detect the base branch (default `develop`, fallback to `main` or `master` if `develop` does not exist):
+```bash
+BASE=$(git branch -r | grep -E 'origin/(develop|main|master)' | sed 's|.*origin/||' | head -1)
+BASE=${BASE:-main}
+```
+
+Run:
+```bash
+git log --oneline $(git merge-base HEAD $BASE)..HEAD
+git diff $(git merge-base HEAD $BASE)..HEAD --stat
+```
+
+Check for a plan file: `ls docs/plans/*.md` sorted by date — use the most recent one if it exists.
+
+## Step 2 — Draft PR
+
+Generate:
+- **Title**: conventional, ≤ 70 chars, derived from commits or task description
+- **Body**: summary of what changed + why, plan reference if found, verification checklist
+
+Template:
+```markdown
+## Summary
+<2-4 bullet points of what changed>
+
+## Plan
+<link to docs/plans/YYYY-MM-DD-slug.md if found>
+
+## Verification
+- [ ] Tests pass
+- [ ] Smoke check
+- [ ] No secrets committed (git log --all --full-history -- "**/secrets/**")
+
+🤖 Generated with [brain taip-workflow-git-pr](https://taip.is)
+```
+
+Show the draft and ask: "Create PR with this title and description? (Y / edit)"
+
+## Step 3 — Create PR (via the GitHub MCP tool)
+
+On confirmation, open the PR through the **`github` MCP tool** — do **NOT** shell out to `gh`
+(it is absent from the hosted/agent images and fails on SSH-only remotes).
+
+**a. Derive the PR coordinates:**
+```bash
+ORIGIN=$(git remote get-url origin)
+# Strip the git@host: / https://host/ prefix and any trailing .git → owner/repo
+SLUG=$(printf '%s' "$ORIGIN" | sed -E 's#^(git@[^:]+:|https?://[^/]+/)##; s#\.git$##')
+OWNER=${SLUG%%/*}; REPO=${SLUG##*/}
+OWNER=${OWNER:-taip-ai}                 # default org
+HEAD=$(git rev-parse --abbrev-ref HEAD) # current feature branch
+# BASE resolved in Step 1 (default develop)
+```
+
+**b. Ensure HEAD is pushed** (GitHub needs the branch to exist on the remote):
+```bash
+git push -u origin "$HEAD"
+```
+
+**c. Call `create_pull_request`** — tool id `mcp__github__create_pull_request` in Claude Code
+(`github__create_pull_request` behind the taip-tools proxy) with:
+```json
+{ "owner": "$OWNER", "repo": "$REPO", "base": "$BASE", "head": "$HEAD",
+  "title": "<title>", "body": "<body>" }
+```
+Print the returned `html_url`.
+
+**d. Fallback** — if the `github` tool is unavailable or `create_pull_request` errors, print the
+compare link so the user can open the PR manually, plus the drafted title and body:
+```
+https://github.com/$OWNER/$REPO/compare/$BASE...$HEAD?expand=1
+```
+
+## Rules
+
+- MUST NOT create PR while on main/master
+- MUST NOT create PR with uncommitted changes
+- MUST NOT shell out to `gh` — open PRs via the `github` MCP tool (`create_pull_request`)
+- PR description MUST include verification checklist

package/packs/process/skills/taip-workflow-plane-init/SKILL.md

@@ -0,0 +1,188 @@
+---
+id: process/skills/taip-workflow-plane-init
+version: 2.0.1
+trigger: "plane init|plane setup|init plane|setup plane|setup plane projects|create plane projects|deploy sprint runner|sprint runner setup"
+description: >
+  Full bootstrap for the Plane + n8n sprint runner stack. Covers: deploy n8n and sprint
+  scripts to fridholmi, verify Plane API, create missing projects (with sprint label +
+  initial cycle), write SPRINT_PROJECTS into n8n config, restart n8n. Runs end-to-end
+  without manual steps. Requires: SSH access to fridholmi, plane_api_token in secrets.
+user-invocable: true
+tags: [plane, project-management, setup, sprint, n8n, init, deploy]
+attribution:
+  source: original
+  license: brain-official
+  author: brain Official
+---
+
+# taip-workflow-plane-init
+
+Full Plane + sprint runner bootstrap. Zero manual steps.
+
+Reference files (all in `fh-smarthome-docker`):
+- `openclaw/sprint/projects.json` — repo ↔ Plane project mapping
+- `openclaw/sprint/setup-plane-projects.sh` — project creation script
+- `ansible/deploy-n8n-sprint.sh` — n8n + sprint deploy script
+- `n8n/docker-compose.yml` — n8n service config
+
+---
+
+## Step 1 — Read current config
+
+Read `openclaw/sprint/projects.json`. Confirm:
+- `plane_api_url` is set
+- At least one project entry exists with `workspace_slug`, `name`, `identifier`, `repo`
+
+If `default_workspace_slug` is missing, ask for the primary Plane workspace slug.
+
+---
+
+## Step 2 — Check Plane API token
+
+```bash
+ls -la openclaw/secrets/local/plane_api_token 2>/dev/null && wc -c openclaw/secrets/local/plane_api_token
+```
+
+If missing or empty:
+- Ask: "Paste your Plane API token (Profile → API Tokens in the Plane UI):"
+- Write it: `echo "<token>" > openclaw/secrets/local/plane_api_token && chmod 0600 openclaw/secrets/local/plane_api_token`
+
+---
+
+## Step 3 — Check if n8n is deployed on the server
+
+```bash
+ssh fridholmi "docker ps --filter name=fridholmit_n8n --format '{{.Names}}\t{{.Status}}' 2>/dev/null || echo 'not running'"
+```
+
+**If n8n is already running:** skip to Step 5.
+
+**If n8n is not running:** check if the deploy directory exists:
+```bash
+ssh fridholmi "ls ~/fh-sprint/n8n/docker-compose.yml 2>/dev/null && echo 'deployed' || echo 'not deployed'"
+```
+
+---
+
+## Step 4 — Deploy n8n + sprint runner (if needed)
+
+```bash
+bash openclaw/sprint/deploy-n8n-sprint.sh --host fridholmi --start
+```
+
+Wait for confirmation that n8n started:
+```bash
+ssh fridholmi "docker ps --filter name=fridholmit_n8n --format '{{.Names}}\t{{.Status}}'"
+```
+
+If n8n fails to start, check logs:
+```bash
+ssh fridholmi "docker logs fridholmit_n8n --tail=30"
+```
+
+---
+
+## Step 5 — Verify Plane API connectivity
+
+```bash
+TOKEN=$(cat openclaw/secrets/local/plane_api_token)
+PLANE_URL=$(python3 -c "import json; d=json.load(open('openclaw/sprint/projects.json')); print(d['plane_api_url'])")
+curl -sf "${PLANE_URL}/api/v1/users/me/" -H "X-Api-Key: ${TOKEN}" | python3 -c "import sys,json; d=json.load(sys.stdin); print('Authenticated as:', d.get('email'))"
+```
+
+Note: Plane 1.3.x `/api/v1/workspaces/` returns 404 — use `/api/v1/users/me/` to verify.
+
+If this fails:
+- 401: wrong token → go back to Step 2
+- Connection refused: Plane is down → `ssh fridholmi "docker ps --filter name=plane"`
+
+---
+
+## Step 6 — Create missing Plane projects (dry-run first)
+
+Copy the setup script to fridholmi if not already there:
+```bash
+rsync -av openclaw/sprint/setup-plane-projects.sh openclaw/sprint/projects.json \
+  fridholmi:~/fh-sprint/openclaw/sprint/
+```
+
+Run dry-run on the server:
+```bash
+ssh fridholmi "cd ~/fh-sprint && bash openclaw/sprint/setup-plane-projects.sh --dry-run"
+```
+
+Show output to user. Ask: "Create these projects? (Y/N)"
+
+WAIT for confirmation.
+
+---
+
+## Step 7 — Create projects + update n8n config
+
+```bash
+ssh fridholmi "cd ~/fh-sprint && bash openclaw/sprint/setup-plane-projects.sh --update-compose"
+```
+
+This:
+1. Creates missing Plane projects via REST API
+2. Creates the `ai-task` sprint label in each new project
+3. Creates "Sprint 1" cycle (today → +14 days)
+4. Writes `SPRINT_PROJECTS` into `~/fh-sprint/n8n/docker-compose.yml`
+
+---
+
+## Step 8 — Restart n8n to pick up SPRINT_PROJECTS
+
+```bash
+ssh fridholmi "cd ~/fh-sprint && docker compose --project-directory . -f n8n/docker-compose.yml --env-file .env up -d"
+```
+
+Verify:
+```bash
+ssh fridholmi "docker ps --filter name=fridholmit_n8n --format '{{.Names}}\t{{.Status}}'"
+```
+
+---
+
+## Step 9 — Set TELEGRAM_CHAT_ID (if not set)
+
+Check if it's configured:
+```bash
+ssh fridholmi "grep TELEGRAM_CHAT_ID ~/fh-sprint/.env"
+```
+
+If empty, ask: "What's your Telegram Chat ID? (from @userinfobot)" and update:
+```bash
+ssh fridholmi "sed -i 's/TELEGRAM_CHAT_ID=/TELEGRAM_CHAT_ID=<id>/' ~/fh-sprint/.env"
+ssh fridholmi "cd ~/fh-sprint && docker compose -f n8n/docker-compose.yml up -d"
+```
+
+---
+
+## Step 10 — Summary
+
+Print:
+```
+✅ Plane sprint runner is ready.
+
+Projects configured:
+  <list from SPRINT_PROJECTS>
+
+n8n UI: http://localhost:5678 (SSH tunnel: ssh -L 5678:127.0.0.1:5678 fridholmi -N)
+
+Remaining manual step:
+  Add SSH credential 'Host SSH' in n8n UI → Settings → Credentials
+  (sshPrivateKey pointing to the server's SSH key)
+
+To run a sprint: open n8n → 'Plane Sprint Runner' → Execute workflow
+```
+
+---
+
+## Hard fails
+
+- MUST NOT create projects without running dry-run and getting user confirmation first
+- MUST NOT write API tokens to any file other than `openclaw/secrets/local/plane_api_token`
+- MUST NOT modify `n8n/docker-compose.yml` directly — the `--update-compose` flag on `setup-plane-projects.sh` handles this safely
+- Plane 1.3.x quirks: hyphens in project names are rejected (script auto-converts to spaces); cycle creation requires `project_id` in body AND `cycle_view: true` on the project; `/api/v1/workspaces/` returns 404 (use `/api/v1/users/me/` for connectivity check)
+- If n8n fails to start after 3 attempts: stop and show logs — do not retry silently