specweave 0.28.20 → 0.28.24

package/dist/src/utils/multi-project-detector.js

@@ -0,0 +1,369 @@
+/**
+ * Multi-Project Detector
+ *
+ * Detects multi-project/umbrella configuration from:
+ * 1. config.json (umbrella.enabled, multiProject.enabled)
+ * 2. childRepos configuration
+ * 3. Project folders in specs/
+ * 4. Sync profile projects
+ *
+ * Used by PM Agent, spec generators, and initial-increment-generator
+ * to determine whether to generate project-scoped user stories.
+ *
+ * @module utils/multi-project-detector
+ */
+import * as fs from './fs-native.js';
+import path from 'path';
+/**
+ * Default project prefixes for common architectures
+ */
+const DEFAULT_PROJECT_PREFIXES = {
+    'fe': 'FE',
+    'frontend': 'FE',
+    'web': 'FE',
+    'ui': 'FE',
+    'client': 'FE',
+    'be': 'BE',
+    'backend': 'BE',
+    'api': 'BE',
+    'server': 'BE',
+    'service': 'BE',
+    'shared': 'SHARED',
+    'common': 'SHARED',
+    'lib': 'SHARED',
+    'types': 'SHARED',
+    'mobile': 'MOBILE',
+    'ios': 'MOBILE',
+    'android': 'MOBILE',
+    'app': 'MOBILE',
+    'infra': 'INFRA',
+    'infrastructure': 'INFRA',
+    'devops': 'INFRA',
+    'deploy': 'INFRA',
+};
+/**
+ * Infer project prefix from project ID/name
+ */
+export function inferProjectPrefix(projectId) {
+    const normalizedId = projectId.toLowerCase();
+    // Check for exact matches first
+    if (DEFAULT_PROJECT_PREFIXES[normalizedId]) {
+        return DEFAULT_PROJECT_PREFIXES[normalizedId];
+    }
+    // Check for suffix matches (e.g., 'my-app-fe' → 'FE')
+    for (const [key, prefix] of Object.entries(DEFAULT_PROJECT_PREFIXES)) {
+        if (normalizedId.endsWith(`-${key}`) || normalizedId.endsWith(`_${key}`)) {
+            return prefix;
+        }
+    }
+    // Check for contains (e.g., 'frontend-service' → 'FE')
+    for (const [key, prefix] of Object.entries(DEFAULT_PROJECT_PREFIXES)) {
+        if (normalizedId.includes(key)) {
+            return prefix;
+        }
+    }
+    // Default: uppercase first part of ID
+    const parts = projectId.split(/[-_]/);
+    return parts[0].toUpperCase().slice(0, 6);
+}
+/**
+ * Parse project configuration from childRepos
+ */
+function parseChildRepos(childRepos) {
+    const projects = [];
+    for (const repo of childRepos) {
+        if (!repo.id)
+            continue;
+        projects.push({
+            id: repo.id,
+            prefix: repo.prefix || inferProjectPrefix(repo.id),
+            name: repo.displayName || repo.id,
+            path: repo.path
+        });
+    }
+    return projects;
+}
+/**
+ * Parse project configuration from multiProject.projects
+ */
+function parseMultiProjectConfig(projectsConfig) {
+    const projects = [];
+    for (const [id, config] of Object.entries(projectsConfig)) {
+        if (typeof config !== 'object')
+            continue;
+        projects.push({
+            id: id,
+            prefix: config.prefix || inferProjectPrefix(id),
+            name: config.name || config.displayName || id,
+            path: config.path
+        });
+    }
+    return projects;
+}
+/**
+ * Detect projects from specs folder structure
+ */
+function detectProjectsFromFolders(specsPath) {
+    const projects = [];
+    if (!fs.existsSync(specsPath)) {
+        return projects;
+    }
+    try {
+        const entries = fs.readdirSync(specsPath, { withFileTypes: true });
+        for (const entry of entries) {
+            // Skip non-directories and special folders
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith('.') || entry.name.startsWith('_'))
+                continue;
+            if (entry.name === 'default')
+                continue;
+            projects.push({
+                id: entry.name,
+                prefix: inferProjectPrefix(entry.name),
+                name: entry.name,
+                path: path.join(specsPath, entry.name)
+            });
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return projects;
+}
+/**
+ * Parse projects from sync profile configuration
+ */
+function parseProjectsFromSyncProfiles(syncConfig) {
+    const projects = [];
+    const seenIds = new Set();
+    if (!syncConfig?.profiles)
+        return projects;
+    for (const [, profile] of Object.entries(syncConfig.profiles)) {
+        const profileConfig = profile?.config;
+        if (!profileConfig)
+            continue;
+        // Check for boardMapping (JIRA)
+        if (profileConfig.boardMapping) {
+            for (const [boardName, projectId] of Object.entries(profileConfig.boardMapping)) {
+                const id = String(projectId);
+                if (seenIds.has(id))
+                    continue;
+                seenIds.add(id);
+                projects.push({
+                    id: id,
+                    prefix: inferProjectPrefix(id),
+                    name: boardName || id
+                });
+            }
+        }
+        // Check for areaPathMapping (ADO)
+        if (profileConfig.areaPathMapping) {
+            for (const [areaPath, projectId] of Object.entries(profileConfig.areaPathMapping)) {
+                const id = String(projectId);
+                if (seenIds.has(id))
+                    continue;
+                seenIds.add(id);
+                projects.push({
+                    id: id,
+                    prefix: inferProjectPrefix(id),
+                    name: areaPath.split('\\').pop() || id
+                });
+            }
+        }
+        // Check for projects array
+        if (profileConfig.projects && Array.isArray(profileConfig.projects)) {
+            for (const projectId of profileConfig.projects) {
+                const id = String(projectId);
+                if (seenIds.has(id))
+                    continue;
+                seenIds.add(id);
+                projects.push({
+                    id: id,
+                    prefix: inferProjectPrefix(id),
+                    name: id
+                });
+            }
+        }
+    }
+    return projects;
+}
+/**
+ * Detect multi-project configuration
+ *
+ * @param projectRoot - Path to project root (default: process.cwd())
+ * @returns Detection result with project information
+ */
+export function detectMultiProjectMode(projectRoot = process.cwd()) {
+    const configPath = path.join(projectRoot, '.specweave', 'config.json');
+    const specsPath = path.join(projectRoot, '.specweave', 'docs', 'internal', 'specs');
+    let config = {};
+    // Read config.json if exists
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            // Ignore parse errors
+        }
+    }
+    // Check 1: umbrella.enabled with 2+ child repos
+    if (config.umbrella?.enabled === true) {
+        const projects = config.umbrella?.childRepos
+            ? parseChildRepos(config.umbrella.childRepos)
+            : [];
+        // Multi-project requires 2+ projects (1 project = single-project mode)
+        if (projects.length > 1) {
+            return {
+                isMultiProject: true,
+                detectionReason: 'umbrella.enabled with childRepos',
+                projects,
+                umbrellaEnabled: true,
+                hasBoardMapping: false
+            };
+        }
+    }
+    // Check 2: multiProject.enabled with 2+ projects
+    if (config.multiProject?.enabled === true) {
+        const projects = config.multiProject?.projects
+            ? parseMultiProjectConfig(config.multiProject.projects)
+            : [];
+        // Multi-project requires 2+ projects (1 project = single-project mode)
+        if (projects.length > 1) {
+            return {
+                isMultiProject: true,
+                detectionReason: 'multiProject.enabled with projects config',
+                projects,
+                umbrellaEnabled: false,
+                hasBoardMapping: false
+            };
+        }
+    }
+    // Check 3: Sync profile with board/area path mapping
+    if (config.sync?.profiles) {
+        const syncProjects = parseProjectsFromSyncProfiles(config.sync);
+        const hasBoardMapping = Object.values(config.sync.profiles).some((p) => p?.config?.boardMapping || p?.config?.areaPathMapping);
+        if (syncProjects.length > 1) {
+            return {
+                isMultiProject: true,
+                detectionReason: 'sync profiles with multiple projects',
+                projects: syncProjects,
+                umbrellaEnabled: false,
+                hasBoardMapping
+            };
+        }
+    }
+    // Check 4: Multiple project folders in specs/
+    const folderProjects = detectProjectsFromFolders(specsPath);
+    if (folderProjects.length > 1) {
+        return {
+            isMultiProject: true,
+            detectionReason: 'multiple project folders in specs/',
+            projects: folderProjects,
+            umbrellaEnabled: false,
+            hasBoardMapping: false
+        };
+    }
+    // Single project mode
+    return {
+        isMultiProject: false,
+        detectionReason: 'no multi-project configuration detected',
+        projects: [],
+        umbrellaEnabled: false,
+        hasBoardMapping: false
+    };
+}
+/**
+ * Get project prefixes for user story generation
+ *
+ * @param projectRoot - Path to project root
+ * @returns Array of project prefixes (e.g., ['FE', 'BE', 'SHARED'])
+ */
+export function getProjectPrefixes(projectRoot = process.cwd()) {
+    const detection = detectMultiProjectMode(projectRoot);
+    if (!detection.isMultiProject || detection.projects.length === 0) {
+        return [];
+    }
+    return detection.projects.map(p => p.prefix);
+}
+/**
+ * Get project by prefix
+ *
+ * @param prefix - Project prefix (e.g., 'FE')
+ * @param projectRoot - Path to project root
+ * @returns Project or undefined
+ */
+export function getProjectByPrefix(prefix, projectRoot = process.cwd()) {
+    const detection = detectMultiProjectMode(projectRoot);
+    return detection.projects.find(p => p.prefix.toUpperCase() === prefix.toUpperCase());
+}
+/**
+ * Format user story ID with project prefix (if multi-project)
+ *
+ * @param storyNumber - Story number (1, 2, 3...)
+ * @param projectPrefix - Optional project prefix (e.g., 'FE')
+ * @param projectRoot - Path to project root
+ * @returns Formatted ID (e.g., 'US-FE-001' or 'US-001')
+ */
+export function formatUserStoryId(storyNumber, projectPrefix, projectRoot = process.cwd()) {
+    const paddedNumber = String(storyNumber).padStart(3, '0');
+    if (projectPrefix) {
+        return `US-${projectPrefix.toUpperCase()}-${paddedNumber}`;
+    }
+    // Auto-detect if multi-project
+    const detection = detectMultiProjectMode(projectRoot);
+    if (detection.isMultiProject) {
+        // If multi-project but no prefix provided, use generic format
+        // (caller should provide prefix for proper scoping)
+        return `US-${paddedNumber}`;
+    }
+    return `US-${paddedNumber}`;
+}
+/**
+ * Format acceptance criteria ID with project prefix (if multi-project)
+ *
+ * @param userStoryNumber - User story number (1, 2, 3...)
+ * @param acNumber - Acceptance criteria number within story (1, 2, 3...)
+ * @param projectPrefix - Optional project prefix (e.g., 'FE')
+ * @returns Formatted ID (e.g., 'AC-FE-US1-01' or 'AC-US1-01')
+ */
+export function formatAcceptanceCriteriaId(userStoryNumber, acNumber, projectPrefix) {
+    const paddedAcNumber = String(acNumber).padStart(2, '0');
+    if (projectPrefix) {
+        return `AC-${projectPrefix.toUpperCase()}-US${userStoryNumber}-${paddedAcNumber}`;
+    }
+    return `AC-US${userStoryNumber}-${paddedAcNumber}`;
+}
+/**
+ * Generate template variables for multi-project spec
+ *
+ * @param detection - Multi-project detection result
+ * @returns Template variable map
+ */
+export function generateMultiProjectTemplateVars(detection) {
+    const vars = {
+        MULTI_PROJECT: detection.isMultiProject ? 'true' : 'false'
+    };
+    if (!detection.isMultiProject) {
+        return vars;
+    }
+    // Add project-specific variables
+    for (const project of detection.projects) {
+        const prefixUpper = project.prefix.toUpperCase();
+        vars[`PROJECT_${prefixUpper}_ID`] = project.id;
+        vars[`PROJECT_${prefixUpper}_PREFIX`] = project.prefix;
+        vars[`PROJECT_${prefixUpper}_NAME`] = project.name;
+    }
+    // Add common project IDs for templates
+    const feProject = detection.projects.find(p => p.prefix.toUpperCase() === 'FE');
+    const beProject = detection.projects.find(p => p.prefix.toUpperCase() === 'BE');
+    const sharedProject = detection.projects.find(p => p.prefix.toUpperCase() === 'SHARED' || p.prefix.toUpperCase() === 'COMMON');
+    if (feProject)
+        vars.PROJECT_FE_ID = feProject.id;
+    if (beProject)
+        vars.PROJECT_BE_ID = beProject.id;
+    if (sharedProject)
+        vars.PROJECT_SHARED_ID = sharedProject.id;
+    return vars;
+}
+//# sourceMappingURL=multi-project-detector.js.map

package/dist/src/utils/multi-project-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-project-detector.js","sourceRoot":"","sources":["../../../src/utils/multi-project-detector.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.28.20",
+  "version": "0.28.24",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/agents/pm/AGENT.md

@@ -445,24 +445,44 @@ graph TD
 
 **YOU MUST CHECK THIS BEFORE WRITING ANY USER STORIES:**
 
-```bash
-# 1. Check config.json for umbrella mode
-cat .specweave/config.json | jq '.umbrella.enabled'
+**Detection Utility** (`src/utils/multi-project-detector.ts`): SpecWeave has automated multi-project detection. When generating specs programmatically, use `detectMultiProjectMode(projectRoot)`. For manual checks, run these commands:
 
-# 2. Check for childRepos
-cat .specweave/config.json | jq '.umbrella.childRepos[]'
+```bash
+# Quick check: Is multi-project mode enabled?
+Read .specweave/config.json and check for:
+# - umbrella.enabled: true
+# - multiProject.enabled: true
+# - umbrella.childRepos[] (array of repos)
+# - sync.profiles[].config.boardMapping or areaPathMapping
 
-# 3. Check for project folders
-ls -la .specweave/docs/internal/specs/
+# Alternative: Check for multiple project folders
+Glob ".specweave/docs/internal/specs/*/" and count directories
+# If > 1 directory (excluding 'default') → multi-project mode
 ```
 
 **Decision Flow:**
 ```
-Is umbrella.enabled: true?
-  → YES → MUST use project-scoped user stories (US-FE-001, US-BE-001)
-  → NO → Check for multiple project folders in specs/
-          → YES → MUST use project-scoped user stories
-          → NO → Use standard user stories (US-001, US-002)
+Step 1: Read .specweave/config.json
+Step 2: Check THESE conditions (ANY = multi-project):
+  ├─ umbrella.enabled === true AND childRepos.length > 0?
+  │   → YES → Use project prefixes from childRepos[].prefix
+  ├─ multiProject.enabled === true AND projects object has keys?
+  │   → YES → Use project prefixes from projects object
+  ├─ sync.profiles[].config.boardMapping exists?
+  │   → YES → Use project IDs from boardMapping values
+  ├─ Multiple folders in .specweave/docs/internal/specs/?
+  │   → YES → Use folder names as project IDs
+  └─ User prompt mentions "frontend", "backend", "3 repos"?
+      → YES → Ask user to confirm project prefixes
+
+Step 3: If multi-project detected:
+  → MUST use project-scoped user stories (US-FE-001, US-BE-001)
+  → MUST use project-scoped ACs (AC-FE-US1-01, AC-BE-US1-01)
+  → Include 'projects:' array in spec.md frontmatter
+
+Step 4: If NO multi-project config:
+  → Use standard user stories (US-001, US-002)
+  → Use standard ACs (AC-US1-01, AC-US2-01)
 ```
 
 **If multi-project detected, NEVER generate:**
@@ -472,6 +492,7 @@ Is umbrella.enabled: true?
 **ALWAYS generate:**
 - ✅ `US-FE-001`, `US-BE-001`, `US-SHARED-001` (project-scoped)
 - ✅ `AC-FE-US1-01`, `AC-BE-US1-01` (project-scoped ACs)
+- ✅ Frontmatter with `multi_project: true` and `projects:` array
 
 ---
 

package/plugins/specweave/commands/specweave-import-external.md

@@ -347,7 +347,7 @@ No tasks defined.
 - **NO automatic increment creation**: Imported items live in living docs ONLY
   - User must manually create increment when ready to work on external item
 - **Read-only snapshot**: External items are imported as static snapshots
-  - No bidirectional sync (external tool → SpecWeave only)
+  - No two-way sync (external tool → SpecWeave only)
 - **Pagination**: Large imports (500+ items) may take several minutes
 - **API quota**: Uses GitHub/JIRA/ADO API quota
   - GitHub: 5000 requests/hour (authenticated)

package/plugins/specweave/commands/specweave.md

@@ -43,7 +43,7 @@ Claude Code does not support command routing. Each command must be invoked direc
 | Command | Description | Example |
 |---------|-------------|---------|
 | `/specweave-github:create-issue` | Create GitHub issue | `/specweave-github:create-issue 0031` |
-| `/specweave-github:sync` | Bidirectional sync | `/specweave-github:sync 0031` |
+| `/specweave-github:sync` | Two-way sync | `/specweave-github:sync 0031` |
 | `/specweave-github:sync-tasks` | Sync tasks as sub-issues | `/specweave-github:sync-tasks 0031` |
 | `/specweave-github:close-issue` | Close GitHub issue | `/specweave-github:close-issue 0031` |
 | `/specweave-github:status` | Show sync status | `/specweave-github:status` |

package/plugins/specweave/skills/increment-planner/SKILL.md

@@ -134,20 +134,13 @@ Every increment MUST have `metadata.json` or:
 
 **⚠️ CRITICAL: Before creating ANY user stories, detect if this is a multi-project (umbrella) setup!**
 
-```bash
-# 1. Check config.json for umbrella mode
-UMBRELLA_ENABLED=$(cat .specweave/config.json 2>/dev/null | jq -r '.umbrella.enabled // false')
-
-# 2. Check for childRepos
-CHILD_REPOS=$(cat .specweave/config.json 2>/dev/null | jq -r '.umbrella.childRepos[]?.id // empty' | tr '\n' ',')
+**Automated Detection**: `src/utils/multi-project-detector.ts` provides `detectMultiProjectMode(projectRoot)` which checks ALL config formats and returns `{ isMultiProject, projects, detectionReason }`.
 
-# 3. Check for project folders in specs/
-PROJECT_FOLDERS=$(ls -1 .specweave/docs/internal/specs/ 2>/dev/null | grep -v "^_" | head -5)
-
-echo "Multi-project mode: $UMBRELLA_ENABLED"
-echo "Child repos: $CHILD_REPOS"
-echo "Project folders: $PROJECT_FOLDERS"
-```
+**Manual check (for agents)**: Read `.specweave/config.json` and check:
+- `umbrella.enabled: true` with `childRepos[]`
+- `multiProject.enabled: true` with `projects{}`
+- `sync.profiles[].config.boardMapping` exists
+- Multiple folders in `.specweave/docs/internal/specs/`
 
 **If multi-project detected (`umbrella.enabled: true` OR multiple project folders exist):**
 - ✅ **MUST** generate project-scoped user stories: `US-FE-001`, `US-BE-001`, `US-SHARED-001`

package/plugins/specweave/skills/spec-generator/SKILL.md

@@ -360,18 +360,13 @@ spec_generator:
 
 ### Detection (MANDATORY FIRST STEP)
 
-**Before generating spec.md, ALWAYS check for multi-project mode:**
+**Automated Detection**: Use `detectMultiProjectMode(projectRoot)` from `src/utils/multi-project-detector.ts`. This utility checks ALL config formats automatically.
 
-```bash
-# 1. Check config.json for umbrella mode
-cat .specweave/config.json | jq '.umbrella.enabled'
-
-# 2. Check for childRepos configuration
-cat .specweave/config.json | jq '.umbrella.childRepos[]'
-
-# 3. Check for project folders in specs/
-ls -la .specweave/docs/internal/specs/
-```
+**Manual check (for agents)**: Read `.specweave/config.json` and check:
+- `umbrella.enabled` + `childRepos[]`
+- `multiProject.enabled` + `projects{}`
+- `sync.profiles[].config.boardMapping`
+- Multiple folders in `.specweave/docs/internal/specs/`
 
 **If ANY of these conditions are TRUE → Multi-project mode ACTIVE:**
 - `umbrella.enabled: true` in config.json

package/plugins/specweave-ado/commands/specweave-ado-sync.md

@@ -1,29 +1,29 @@
 ---
 name: specweave-ado:sync
-description: Bidirectional sync between SpecWeave increment and Azure DevOps work item (two-way sync by default)
+description: Two-way sync between SpecWeave increment and Azure DevOps work item (push & pull by default)
 ---
 
 # Sync ADO Work Item Command
 
 **Usage**: `/specweave-ado:sync <increment-id> [options]`
 
-**Purpose**: Bidirectional synchronization between SpecWeave increment and Azure DevOps work item
+**Purpose**: Two-way synchronization between SpecWeave increment and Azure DevOps work item
 
-**Default**: Two-way sync (bidirectional)
+**Default**: Two-way sync (push & pull)
 
 ---
 
 ## Options
 
-- `--direction <mode>`: Sync direction (default: `bidirectional`)
-  - `bidirectional`: SpecWeave ↔ ADO (default - recommended)
+- `--direction <mode>`: Sync direction (default: `two-way`)
+  - `two-way`: SpecWeave ↔ ADO (default - recommended)
   - `to-ado`: SpecWeave → ADO only (push progress)
   - `from-ado`: ADO → SpecWeave only (pull updates)
 
 ## Examples
 
 ```bash
-# Bidirectional sync (default - two-way)
+# Two-way sync (default - both directions)
 /specweave-ado:sync 0005
 
 # Push only (one-way to ADO)
@@ -37,7 +37,7 @@ description: Bidirectional sync between SpecWeave increment and Azure DevOps wor
 
 ## Command Behavior
 
-When user runs this command, invoke `ado-manager` agent to perform bidirectional sync:
+When user runs this command, invoke `ado-manager` agent to perform two-way sync:
 
 ### Phase 1: Pull FROM ADO (default behavior)
 1. Fetch work item state from ADO API
@@ -66,7 +66,7 @@ When user runs this command, invoke `ado-manager` agent to perform bidirectional
 ```
 Use Task tool with subagent_type: "specweave-ado:ado-manager:ado-manager"
 
-Prompt: "Bidirectional sync for increment 0005-payment-integration with ADO.
+Prompt: "Two-way sync for increment 0005-payment-integration with ADO.
 
 Phase 1 - Pull FROM ADO:
 1. Fetch work item #12345 from ADO API
@@ -83,20 +83,20 @@ Phase 2 - Push TO ADO:
 6. POST comment to ADO API
 7. Update work item state/fields
 
-Display: Bidirectional sync summary"
+Display: Two-way sync summary"
 ```
 
 ---
 
 ## Example Output
 
-### Bidirectional Sync (Default)
+### Two-way Sync (Default)
 
 ```
-🔄 Bidirectional sync for increment 0005...
+🔄 Two-way sync for increment 0005...
 
 ✓ Azure DevOps work item: #12345
-✓ Sync direction: bidirectional (two-way)
+✓ Sync direction: Two-way (push & pull)
 
 Detecting changes (both directions)...
 

package/plugins/specweave-github/agents/github-manager/AGENT.md

@@ -38,7 +38,7 @@ GitHub issues MUST use living docs format:
 
 **Tools**: Read, Write, Edit, Bash (GitHub CLI)
 
-**Default Behavior**: **Bidirectional sync** (two-way) - Synchronizes changes in both directions automatically
+**Default Behavior**: **Two-way sync** (push & pull) - Synchronizes changes in both directions automatically
 
 ---
 
@@ -69,8 +69,8 @@ Task({
 
 As the GitHub Manager agent, I specialize in:
 
-### 1. Bidirectional Synchronization (Default)
-- **Two-Way Sync**: Keep SpecWeave and GitHub synchronized automatically
+### 1. Two-way Synchronization (Default)
+- **Two-way Sync**: Keep SpecWeave and GitHub synchronized automatically
   - **FROM GitHub**: Pull status changes, labels, comments, state updates
   - **TO GitHub**: Push task completion, progress updates, metadata
 - **Conflict Resolution**: Detect and resolve conflicts between systems
@@ -79,7 +79,7 @@ As the GitHub Manager agent, I specialize in:
 
 ### 2. Issue Management
 - **Create Issues**: Generate well-formatted GitHub issues from increment specs
-- **Update Issues**: Sync progress, add comments, update labels (bidirectional)
+- **Update Issues**: Sync progress, add comments, update labels (two-way)
 - **Close Issues**: Close issues with completion summaries
 - **Link Issues**: Connect related issues, PRs, and increments
 - **Bulk Operations**: Batch create/update/close issues
@@ -87,7 +87,7 @@ As the GitHub Manager agent, I specialize in:
 ### 3. Progress Tracking
 - **Task Checklists**: Generate and update task checklists in issues
 - **Progress Comments**: Post detailed task completion comments
-- **Status Updates**: Bidirectional sync of increment status ↔ GitHub issue state
+- **Status Updates**: Two-way sync of increment status ↔ GitHub issue state
 - **Time Tracking**: Track estimated vs actual time per task
 - **Milestone Progress**: Update milestone completion percentages