@chief-clancy/brief 0.1.1 → 0.2.0

package/src/workflows/board-setup.md

@@ -0,0 +1,370 @@
+# Board Setup Workflow
+
+## Overview
+
+Configure board credentials so `/clancy:brief` can fetch tickets and post briefs as comments. This workflow collects the minimum credentials needed for board access — no pipeline configuration, no role settings, no iteration limits.
+
+Credentials are stored in `.clancy/.env` in the current project directory. They are per-project, not global.
+
+---
+
+## Step 1 — Preflight checks
+
+### 1. Check for full pipeline
+
+Check if `.clancy/clancy-implement.js` exists in the project root.
+
+If present, the full Clancy pipeline is installed. Show:
+
+```
+Full Clancy pipeline detected. Use /clancy:settings to manage board credentials.
+```
+
+Stop. Do not proceed with standalone board setup.
+
+### 2. Check for existing credentials
+
+Check if `.clancy/.env` exists and contains board credentials (any of: `JIRA_BASE_URL`, `GITHUB_TOKEN`, `LINEAR_API_KEY`, `SHORTCUT_API_TOKEN`, `NOTION_TOKEN`, `AZDO_ORG`, `AZDO_PAT`, `AZDO_PROJECT`).
+
+If board credentials are found, show:
+
+```
+Existing board credentials found in .clancy/.env.
+
+[1] Reconfigure (replace current board)
+[2] Cancel
+```
+
+If [2]: stop.
+If [1]: continue to Step 2. The existing `.clancy/.env` will be updated (board-specific vars replaced, other vars preserved).
+
+If `.clancy/.env` does not exist, or exists but has no board credentials: continue to Step 2.
+
+---
+
+## Step 2 — Board selection
+
+Output:
+
+```
+Which board are you using?
+
+[1] Jira
+[2] GitHub Issues
+[3] Linear
+[4] Shortcut
+[5] Notion
+[6] Azure DevOps
+[7] My board isn't listed
+```
+
+If the user selects [7], show:
+
+```
+Clancy currently supports Jira, GitHub Issues, Linear, Shortcut, Notion, and Azure DevOps.
+
+Your board isn't supported yet — open an issue:
+  github.com/Pushedskydiver/chief-clancy/issues
+
+You can still use /clancy:brief with inline text or file input:
+  /clancy:brief "Add dark mode support"
+  /clancy:brief --from docs/rfc.md
+```
+
+Stop.
+
+---
+
+## Step 3 — Credential collection
+
+Ask each question individually and wait for an answer before moving to the next.
+
+### Jira
+
+1. `What's your Jira base URL? (e.g. https://your-org.atlassian.net)`
+2. `What's your Jira project key? (e.g. PROJ)`
+3. `What email address do you use to log in to Atlassian?`
+4. `Paste your Jira API token: (create one at id.atlassian.com/manage-profile/security/api-tokens)`
+
+Store as `JIRA_BASE_URL`, `JIRA_PROJECT_KEY`, `JIRA_USER`, `JIRA_API_TOKEN`.
+
+### GitHub Issues
+
+1. `What's your GitHub repo? (owner/name, e.g. acme/my-app)`
+2. `Paste your GitHub personal access token: (needs repo scope)`
+
+Store as `GITHUB_REPO`, `GITHUB_TOKEN`.
+
+After collecting credentials, show:
+
+```
+Note: Clancy only picks up GitHub Issues that have the "clancy" label applied.
+Add this label to any issue you want Clancy to brief.
+```
+
+### Linear
+
+1. `Paste your Linear API key: (create one at linear.app/settings/api)`
+2. After verifying the API key (Step 4), auto-detect teams by querying `{ teams { nodes { id name } } }`.
+   - If exactly 1 team: use it automatically. Show `Using team: {name} ({id})`.
+   - If 2+ teams: show a numbered list and let the user pick.
+   - If the query fails or returns no teams: fall back to asking manually: `What's your Linear team ID? (find it at linear.app/settings/teams — click your team, copy the ID from the URL)`
+
+Store as `LINEAR_API_KEY`, `LINEAR_TEAM_ID`.
+
+### Shortcut
+
+1. `Paste your Shortcut API token: (create one at app.shortcut.com/settings/account/api-tokens)`
+
+Store as `SHORTCUT_API_TOKEN`.
+
+### Notion
+
+1. `Paste your Notion integration token: (create one at notion.so/my-integrations)`
+2. `What's your Notion database ID? (the 32-character hex string in your database URL)`
+
+Store as `NOTION_TOKEN`, `NOTION_DATABASE_ID`.
+
+### Azure DevOps
+
+1. `What's your Azure DevOps organisation name? (e.g. your-org)`
+2. `What's your Azure DevOps project name?`
+3. `Paste your Azure DevOps personal access token: (needs Work Items Read & Write scope)`
+
+Store as `AZDO_ORG`, `AZDO_PROJECT`, `AZDO_PAT`.
+
+---
+
+## Step 4 — Credential verification
+
+After collecting all credentials for the chosen board, verify the connection before writing them.
+
+### Jira
+
+Call `GET {JIRA_BASE_URL}/rest/api/3/project/{JIRA_PROJECT_KEY}` with basic auth (`{JIRA_USER}:{JIRA_API_TOKEN}` base64-encoded in the `Authorization: Basic` header).
+
+On success (HTTP 200):
+
+```
+✅ Jira connected — project {JIRA_PROJECT_KEY} reachable.
+```
+
+### GitHub Issues
+
+Call `GET https://api.github.com/repos/{GITHUB_REPO}` with `Authorization: Bearer {GITHUB_TOKEN}` and `X-GitHub-Api-Version: 2022-11-28`.
+
+On success (HTTP 200):
+
+```
+✅ GitHub connected — {GITHUB_REPO} reachable.
+```
+
+### Linear
+
+Call `POST https://api.linear.app/graphql` with `Authorization: {LINEAR_API_KEY}` (no Bearer prefix) and body `{"query": "{ viewer { id name } }"}`.
+
+On success (HTTP 200 with `data.viewer`):
+
+```
+✅ Linear connected — {viewer.name}.
+```
+
+### Shortcut
+
+Call `GET https://api.app.shortcut.com/api/v3/member-info` with `Shortcut-Token: {SHORTCUT_API_TOKEN}`.
+
+On success (HTTP 200):
+
+```
+✅ Shortcut connected.
+```
+
+### Notion
+
+Call `GET https://api.notion.com/v1/databases/{NOTION_DATABASE_ID}` with `Authorization: Bearer {NOTION_TOKEN}` and `Notion-Version: 2022-06-28`.
+
+On success (HTTP 200):
+
+```
+✅ Notion connected — database reachable.
+```
+
+### Azure DevOps
+
+Call `GET https://dev.azure.com/{AZDO_ORG}/{AZDO_PROJECT}/_apis/wit/workitemtypes?api-version=7.1` with basic auth (empty user, `AZDO_PAT` as password).
+
+On success (HTTP 200):
+
+```
+✅ Azure DevOps connected — {AZDO_PROJECT} reachable.
+```
+
+### On failure (any board)
+
+```
+❌ Couldn't connect to {board} (HTTP {status}).
+Check your credentials.
+
+[1] Re-enter credentials
+[2] Skip verification (save anyway)
+[3] Cancel
+```
+
+If [1]: go back to Step 3 for that board.
+If [2]: save the unverified credentials and continue to Step 5.
+If [3]: stop without saving.
+
+Never silently continue with unverified credentials — the user must explicitly choose.
+
+---
+
+## Step 5 — Detect base branch
+
+Auto-detect the default branch:
+
+```bash
+BASE_BRANCH_REF="$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null)"
+echo "${BASE_BRANCH_REF#refs/remotes/origin/}"
+```
+
+If detection succeeds and the branch is `main` or `master`: use it silently. Store as `CLANCY_BASE_BRANCH`.
+
+If detection fails or returns an unexpected branch name, ask:
+
+```
+What's your base branch? [main]
+```
+
+---
+
+## Step 6 — Write credentials
+
+### Create directory
+
+Create `.clancy/` directory if it does not exist.
+
+### Write `.clancy/.env`
+
+If `.clancy/.env` already exists (reconfigure path from Step 1, or exists with no board credentials):
+
+- Preserve all existing lines (comments, blank lines, non-board vars)
+- Remove any existing board-specific env vars for ALL boards (not just the new one). Board vars to remove:
+  - Jira: `JIRA_BASE_URL`, `JIRA_PROJECT_KEY`, `JIRA_USER`, `JIRA_API_TOKEN`, `CLANCY_JQL_STATUS`, `CLANCY_JQL_SPRINT`
+  - GitHub: `GITHUB_REPO`, `GITHUB_TOKEN`
+  - Linear: `LINEAR_API_KEY`, `LINEAR_TEAM_ID`
+  - Shortcut: `SHORTCUT_API_TOKEN`, `SHORTCUT_WORKFLOW`
+  - Notion: `NOTION_TOKEN`, `NOTION_DATABASE_ID`, `CLANCY_NOTION_STATUS`, `CLANCY_NOTION_ASSIGNEE`, `CLANCY_NOTION_LABELS`, `CLANCY_NOTION_PARENT`, `CLANCY_NOTION_TODO`
+  - Azure DevOps: `AZDO_ORG`, `AZDO_PROJECT`, `AZDO_PAT`, `CLANCY_AZDO_WIT`, `CLANCY_AZDO_STATUS`
+- Preserve all other lines (comments, blank lines, non-board vars like `CLANCY_BASE_BRANCH`)
+- Append the new board's credentials at the end
+- Update `CLANCY_BASE_BRANCH` if it exists, or append it
+
+If `.clancy/.env` does not exist, write a new file:
+
+```
+# Clancy — Board credentials
+# Configured by @chief-clancy/brief
+# Do not commit this file to version control.
+
+{BOARD_CREDENTIALS}
+
+CLANCY_BASE_BRANCH={branch}
+```
+
+Where `{BOARD_CREDENTIALS}` is the board-specific key=value pairs collected in Step 3. Wrap values containing spaces in double quotes.
+
+### Check .gitignore
+
+Check if `.gitignore` exists and contains `.clancy/.env` (or a pattern that covers it, like `.clancy/` or `*.env`).
+
+If not covered, show:
+
+```
+⚠️  Add .clancy/.env to your .gitignore to keep credentials out of version control:
+
+  echo '.clancy/.env' >> .gitignore
+```
+
+---
+
+## Step 7 — Completion
+
+Show the board-specific success message:
+
+### Jira
+
+```
+Board credentials configured for Jira ({JIRA_PROJECT_KEY}).
+
+You can now brief from Jira tickets:
+  /clancy:brief PROJ-123
+
+Credentials are stored in .clancy/.env (this project only).
+To reconfigure: /clancy:board-setup
+For the full pipeline: npx chief-clancy
+```
+
+### GitHub Issues
+
+```
+Board credentials configured for GitHub Issues ({GITHUB_REPO}).
+
+You can now brief from GitHub issues:
+  /clancy:brief #42
+
+Credentials are stored in .clancy/.env (this project only).
+To reconfigure: /clancy:board-setup
+For the full pipeline: npx chief-clancy
+```
+
+### Linear
+
+```
+Board credentials configured for Linear.
+
+You can now brief from Linear issues:
+  /clancy:brief ENG-42
+
+Credentials are stored in .clancy/.env (this project only).
+To reconfigure: /clancy:board-setup
+For the full pipeline: npx chief-clancy
+```
+
+### Shortcut
+
+```
+Board credentials configured for Shortcut.
+
+You can now brief from Shortcut stories:
+  /clancy:brief SC-123
+
+Credentials are stored in .clancy/.env (this project only).
+To reconfigure: /clancy:board-setup
+For the full pipeline: npx chief-clancy
+```
+
+### Notion
+
+```
+Board credentials configured for Notion.
+
+You can now brief from Notion pages:
+  /clancy:brief notion-XXXXXXXX
+
+Credentials are stored in .clancy/.env (this project only).
+To reconfigure: /clancy:board-setup
+For the full pipeline: npx chief-clancy
+```
+
+### Azure DevOps
+
+```
+Board credentials configured for Azure DevOps ({AZDO_PROJECT}).
+
+You can now brief from Azure DevOps work items:
+  /clancy:brief 42
+
+Credentials are stored in .clancy/.env (this project only).
+To reconfigure: /clancy:board-setup
+For the full pipeline: npx chief-clancy
+```

package/src/workflows/brief.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Research an idea, interrogate it thoroughly, and generate a structured strategic brief with vertical-slice ticket decomposition. Briefs are saved locally and optionally posted as comments on the source ticket. Does not create tickets — in **terminal mode**, use `/clancy:approve-brief` for that. In **standalone mode**, install the full pipeline (`npx chief-clancy`) to create tickets from briefs.
+Research an idea, interrogate it thoroughly, and generate a structured strategic brief with vertical-slice ticket decomposition. Briefs are saved locally and optionally posted as comments on the source ticket. Does not create tickets — in **terminal mode**, use `/clancy:approve-brief` for that. In **standalone mode** or **standalone+board mode**, install the full pipeline (`npx chief-clancy`) to create tickets from briefs.
 
 ---
 
@@ -12,12 +12,17 @@ Research an idea, interrogate it thoroughly, and generate a structured strategic
 
 Check for `.clancy/.env`:
 
-- **Present** → **terminal mode**. Full Clancy installation detected.
-- **Absent** → **standalone mode**. Running from `@chief-clancy/brief` only.
+- **Absent** → **standalone mode**. No board credentials. Board ticket and batch modes are blocked.
+- **Present** → continue to `.clancy/clancy-implement.js` check below.
 
-### 2. Terminal-mode preflight (skip in standalone mode)
+If `.clancy/.env` is present, check for `.clancy/clancy-implement.js`:
 
-If `.clancy/.env` is present:
+- **Present** → **terminal mode**. Full Clancy pipeline installed.
+- **Absent** → **standalone+board mode**. Board credentials available via `/clancy:board-setup`. Board ticket mode works. Steps 10/10a work. But `/clancy:approve-brief` is not available (requires full pipeline).
+
+### 2. Terminal-mode preflight (skip in standalone mode and standalone+board mode)
+
+If in **terminal mode** (`.clancy/.env` present AND `.clancy/clancy-implement.js` present):
 
 a. Source `.clancy/.env` and check board credentials are present.
 
@@ -90,8 +95,9 @@ If `--list` is present (with or without other arguments), jump to Step 11 (Brief
 If running in **standalone mode** (Step 1 detected no `.clancy/.env`) and the resolved input mode is **board ticket** or **batch mode**:
 
 ```
-Board credentials not found. To brief from a board ticket, install the
-full Clancy pipeline: npx chief-clancy
+Board credentials not found. To brief from a board ticket:
+  /clancy:board-setup    — configure board credentials (standalone)
+  npx chief-clancy       — install the full pipeline
 
 For now, use:
   /clancy:brief "Add dark mode"       — inline text
@@ -100,6 +106,8 @@ For now, use:
 
 Stop.
 
+In **standalone+board mode**, board ticket and batch modes proceed normally — credentials are available.
+
 ---
 
 ## Step 3 — Gather idea (mode-specific)
@@ -855,7 +863,7 @@ Write to `.clancy/briefs/{YYYY-MM-DD}-{slug}.md`.
 
 ## Step 10 — Post to board
 
-Only for board-sourced briefs in **terminal mode** (ticket key was provided AND `.clancy/.env` is present). In **standalone mode**, skip this step and Step 10a entirely — the local file in `.clancy/briefs/` is the source of truth.
+Only for board-sourced briefs when board credentials are available (terminal mode or standalone+board mode). In **standalone mode** (no `.clancy/.env`), skip this step and Step 10a entirely — the local file in `.clancy/briefs/` is the source of truth.
 
 Inline text and file briefs are also local only — skip this step regardless of mode.
 
@@ -971,7 +979,7 @@ Continue — do not stop. The local file is the source of truth.
 
 ## Step 10a — Apply pipeline label (board-sourced only)
 
-Only for board-sourced briefs in **terminal mode** (ticket key was provided AND `.clancy/.env` is present). In **standalone mode**, skip this step entirely (see Step 10 guard). Inline text and file briefs also skip this step.
+Only for board-sourced briefs when board credentials are available (terminal mode or standalone+board mode). In **standalone mode** (no `.clancy/.env`), skip this step entirely (see Step 10 guard). Inline text and file briefs also skip this step. Note: in standalone+board mode, this step creates a `clancy:brief` label on the board — this is expected behaviour when credentials are configured.
 
 **This step is mandatory for board-sourced briefs — always apply the label.** Use `CLANCY_LABEL_BRIEF` from `.clancy/.env` if set. If not set, use `clancy:brief` as the default. Ensure the label exists on the board (create it if missing), then add it to the ticket. Also read `CLANCY_LABEL_PLAN` (default: `clancy:plan`) and `CLANCY_LABEL_BUILD` (default: `clancy:build`) for cleanup during re-briefs.
 
@@ -1240,7 +1248,7 @@ Clancy — Briefs
 3 unapproved drafts. 1 stale (>7 days).
 
 To approve (terminal mode): /clancy:approve-brief <slug or index>
-To approve (standalone):    npx chief-clancy, then /clancy:approve-brief
+To approve (standalone/standalone+board): npx chief-clancy, then /clancy:approve-brief
 To review stale briefs: open the file and add ## Feedback, or delete it.
 ```
 
@@ -1275,7 +1283,7 @@ Next Steps
     Then re-run: /clancy:brief {KEY}
 
   Approve:       /clancy:approve-brief {KEY}  (terminal mode)
-  Full pipeline: npx chief-clancy             (if standalone)
+  Full pipeline: npx chief-clancy             (if not terminal mode)
   Start over:    /clancy:brief --fresh {KEY}
 ```
 
@@ -1295,7 +1303,7 @@ Next Steps
 
   Approve:       /clancy:approve-brief {slug}           (terminal mode)
   With parent:   /clancy:approve-brief {slug} --epic {KEY}
-  Full pipeline: npx chief-clancy                        (if standalone)
+  Full pipeline: npx chief-clancy                        (if not terminal mode)
   Start over:    /clancy:brief --fresh
 ```
 
@@ -1330,7 +1338,7 @@ Briefed {M} of {N} tickets. {K} skipped.
   ⏭️  [{KEY3}] {Title} — already briefed
   ⏭️  [{KEY4}] {Title} — not relevant
 
-Briefs saved to .clancy/briefs/. To create tickets: /clancy:approve-brief (terminal mode) or install the full pipeline first (npx chief-clancy).
+Briefs saved to .clancy/briefs/. To create tickets: /clancy:approve-brief (requires full pipeline — npx chief-clancy).
 ```
 
 ---

package/src/workflows/workflows.test.ts

@@ -11,7 +11,7 @@ import { describe, expect, it } from 'vitest';
 
 const WORKFLOWS_DIR = fileURLToPath(new URL('.', import.meta.url));
 
-const EXPECTED_WORKFLOWS = ['brief.md'];
+const EXPECTED_WORKFLOWS = ['approve-brief.md', 'board-setup.md', 'brief.md'];
 
 describe('workflows directory structure', () => {
   it('contains exactly the expected workflow files', () => {
@@ -43,15 +43,104 @@ describe('workflows directory structure', () => {
     expect(content).toContain('## Step 1');
     expect(content).toContain('.clancy/briefs/');
   });
+
+  it('approve-brief workflow has structural step markers', () => {
+    const content = readFileSync(
+      new URL('approve-brief.md', import.meta.url),
+      'utf8',
+    );
+
+    expect(content).toContain('## Step 1');
+    expect(content).toContain('.clancy/briefs/');
+  });
 });
 
-describe('standalone mode adaptations', () => {
+// ---------------------------------------------------------------------------
+// board-setup.md content assertions
+// ---------------------------------------------------------------------------
+
+describe('board-setup workflow', () => {
+  const content = readFileSync(
+    new URL('board-setup.md', import.meta.url),
+    'utf8',
+  );
+
+  it('checks for full pipeline before proceeding', () => {
+    expect(content).toContain('clancy-implement.js');
+    expect(content).toContain('/clancy:settings');
+  });
+
+  it('checks for existing board credentials', () => {
+    expect(content).toContain('Existing board credentials found');
+    expect(content).toContain('Reconfigure');
+  });
+
+  it('offers all 6 supported boards', () => {
+    expect(content).toContain('Jira');
+    expect(content).toContain('GitHub Issues');
+    expect(content).toContain('Linear');
+    expect(content).toContain('Shortcut');
+    expect(content).toContain('Notion');
+    expect(content).toContain('Azure DevOps');
+  });
+
+  it('includes credential prompts for each board', () => {
+    expect(content).toContain('JIRA_BASE_URL');
+    expect(content).toContain('GITHUB_TOKEN');
+    expect(content).toContain('LINEAR_API_KEY');
+    expect(content).toContain('SHORTCUT_API_TOKEN');
+    expect(content).toContain('NOTION_TOKEN');
+    expect(content).toContain('AZDO_PAT');
+  });
+
+  it('includes credential verification for each board', () => {
+    expect(content).toContain('Jira connected');
+    expect(content).toContain('GitHub connected');
+    expect(content).toContain('Linear connected');
+    expect(content).toContain('Shortcut connected');
+    expect(content).toContain('Notion connected');
+    expect(content).toContain('Azure DevOps connected');
+  });
+
+  it('offers re-enter, skip, and cancel on verification failure', () => {
+    expect(content).toContain('Re-enter credentials');
+    expect(content).toContain('Skip verification');
+    expect(content).toContain('Cancel');
+  });
+
+  it('warns about .gitignore', () => {
+    expect(content).toContain('.gitignore');
+    expect(content).toContain('.clancy/.env');
+  });
+
+  it('notes credentials are per-project', () => {
+    expect(content).toContain('this project only');
+  });
+
+  it('includes brief header comment in env file', () => {
+    expect(content).toContain('Configured by @chief-clancy/brief');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// brief.md content assertions
+// ---------------------------------------------------------------------------
+
+describe('three-state mode detection', () => {
   const content = readFileSync(new URL('brief.md', import.meta.url), 'utf8');
 
-  it('Step 1 uses standalone/terminal mode detection', () => {
+  it('Step 1 detects three installation states', () => {
     expect(content).toContain('standalone mode');
+    expect(content).toContain('standalone+board mode');
     expect(content).toContain('terminal mode');
-    expect(content).toContain('Detect installation context');
+  });
+
+  it('Step 1 checks .clancy/.env for credentials', () => {
+    expect(content).toContain('.clancy/.env');
+  });
+
+  it('Step 1 checks clancy-implement.js for terminal detection', () => {
+    expect(content).toContain('clancy-implement.js');
   });
 
   it('Step 1 does not hard-stop on missing .clancy/.env', () => {
@@ -60,19 +149,26 @@ describe('standalone mode adaptations', () => {
     );
   });
 
-  it('includes standalone board-ticket guard', () => {
+  it('CLANCY_ROLES check only runs in terminal mode', () => {
+    expect(content).toContain('Terminal-mode preflight');
+    expect(content).toContain(
+      'skip in standalone mode and standalone+board mode',
+    );
+  });
+
+  it('standalone guard mentions /clancy:board-setup', () => {
     expect(content).toContain('Standalone board-ticket guard');
     expect(content).toContain('Board credentials not found');
-    expect(content).toContain('npx chief-clancy');
+    expect(content).toContain('/clancy:board-setup');
   });
 
-  it('Step 10 includes standalone skip guard', () => {
+  it('Step 10 runs when board credentials are available', () => {
     expect(content).toContain(
-      'In **standalone mode**, skip this step and Step 10a entirely',
+      'when board credentials are available (terminal mode or standalone+board mode)',
     );
   });
 
-  it('Step 10a includes standalone skip back-reference', () => {
+  it('Step 10a runs when board credentials are available', () => {
     expect(content).toContain('see Step 10 guard');
   });
 
@@ -81,7 +177,7 @@ describe('standalone mode adaptations', () => {
     expect(content).not.toContain('src/agents/devils-advocate.md');
   });
 
-  it('approve-brief references include standalone context', () => {
+  it('approve-brief references include standalone guidance', () => {
     expect(content).not.toMatch(/that is `\/clancy:approve-brief`\./);
     expect(content).toContain('npx chief-clancy');
   });