External KB scaffold via pair-cli — pure KB repo + release script (reuses pair package)

[rucka]

Story Statement

As an organization wanting a private or self-hosted KB
I want pair-cli to scaffold a new external KB repository (own repo, fork, private/self-hosted)
So that a custom KB installs like the official one, without hand-assembling the structure from scratch

Where: new pair-cli command (e.g. pair scaffold-kb <path>); consumed by teams building their own KB, distinct from the org-KB service track (#149–#162, unchanged)

Epic Context

Parent Epic: Skill marketplace + Quickstart + external KB scaffold #213
Status: Refined
Priority: P1 (Should-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given an empty or existing directory
   When a developer runs the scaffold command
   Then it produces a pure KB repo layout: .pair/knowledge/ + .skills/ (no .pair/adoption/ — a KB is knowledge, not a configured project), a pair.config.json, an operational README, and a .gitignore (excluding dist/ and credentials)

2. Given the scaffolded KB repo
   When the maintainer wants to cut a release
   Then a generated release script/workflow runs pair package (reusing the existing command, not a new release mechanism) to produce a git tag (vX.Y.Z) and a GitHub release with the packaged ZIP attached

3. Given the scaffolded and released KB
   When a separate project installs it via pair install --source <repo> or the published release ZIP
   Then installation succeeds in under 10 minutes, matching the behavior of installing the official KB

4. Given the scaffold command is re-run against its own prior output
   When it completes
   Then the output is regenerable — re-scaffolding does not corrupt or duplicate an already-scaffolded structure (idempotent, same convention as pair install/update's own mirror behavior)

Business Rules

• The CLI does not publish — publishing lives entirely in the generated script/workflow, keeping pair-cli itself code-host agnostic (works with GitHub, GitLab, self-hosted, etc.)
• Distribution channels are exclusive at the project level: a project installs from the marketplace (story Skill marketplace: marketplace.json + plugin packaging for native Claude Code install #277) or an external KB via CLI — never both for the same skill set (D1)
• Reuses pair package entirely for the ZIP/release mechanics — this story only adds scaffolding (new repo structure) and a thin release-script generator that calls the existing command with the right flags

Edge Cases and Error Handling

• Scaffolding into a non-empty directory: warn and ask before overwriting existing files, same pattern as other setup-oriented skills (e.g. pair-capability-setup-gates's "existing conflicting config" handling) — never silently overwrite
• Private/self-hosted repo with no public release hosting: the generated release script documents the ZIP output location even if it can't create a hosted release automatically (e.g. no GitHub Actions available) — degrade to "here's your ZIP, publish it however your org does"
• Re-scaffolding an already-customized KB repo: only regenerates the scaffold-owned files (pair.config.json defaults, release script) with confirmation before overwrite; never touches KB content the maintainer has since authored under .pair/knowledge//.skills/

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• New pair-cli command implemented (scaffold structure, pair.config.json, README, .gitignore, release script/workflow generator)
• Unit tests written and passing (scaffold output structure, idempotent re-run, release-script generation)
• Code review completed and approved
• Documentation updated — docs site (external KB section, cross-linked from CLI reference)

Quality Assurance

• End-to-end test: scaffold a KB repo, add one skill to it, run the generated release script, install the published ZIP into a separate test project via --source, confirm the skill is usable
• Idempotency test: re-run the scaffold command against its own output, confirm no corruption/duplication

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 5 (L)
Confidence Level: Medium
Sizing Justification: new CLI command with several deliverables (scaffold structure, config, release-script generation), but de-risked by reusing pair package for the actual release mechanics instead of building a new one

Sprint Capacity Validation

Sprint Fit Assessment: yes, single sprint
Total Effort Assessment: fits — Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: none functionally, but reuses pair package (already shipped) as a hard dependency for the release-script generator
Dependent Stories: none
Shared Components: pair package's ZIP/metadata/release mechanics (apps/pair-cli/src/commands/package/)

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: end-to-end scaffold → release → install round-trip in a scratch $WORKDIR outside the monorepo (per this project's established manual-test convention); idempotency re-run test
Test Data Requirements: a scratch git repository for the scaffold target, a second scratch project to install into

Notes and Additional Context

Refinement Session Insights: Confirmed during refinement that the release-script generator reuses pair package rather than building a separate release pipeline — pair package already does ZIP creation, metadata, and org-template handling; this story's own scope is scaffolding plus generating the thin script/workflow that invokes it with the right flags.
Documentation Links: Requirements R9.2, R2.13 · Spec G11 · pair-requirements-triage.md G11 addendum (2026-07-06) · org-KB service stories #149–#162 (unchanged, separate channel)

Technical Analysis

Implementation Approach

Technical Strategy: new pair-cli command that (a) writes the pure-KB directory structure + pair.config.json + README + .gitignore, and (b) generates a release script/workflow (e.g. a GitHub Actions workflow file, or an npm/shell script depending on the target code host) that shells out to the already-existing pair package command with appropriate flags, then tags and creates a release
Key Components: new command under apps/pair-cli/src/commands/ (e.g. scaffold-kb); reuses packages/content-ops file-system primitives already used by install/update for consistent scaffolding; reuses pair package unchanged
Integration Points: pair package (release mechanics); pair install --source (the installation path this scaffold's output must work with)

Technical Requirements

• Scaffold output must install cleanly via the existing --source/--url path with zero special-casing — it's a normal KB repo, not a new install code path
• Release script generation must be code-host-aware enough to produce a working script for at least GitHub (the primary target), with graceful degradation noted for others

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Generated release script assumes GitHub-specific mechanics (tags, releases, Actions) that don't translate directly to other code hosts	Medium	Medium	Document the GitHub-first scope explicitly; degrade gracefully (documented manual steps) for non-GitHub hosts, consistent with this KB's existing code-host-agnostic stance (see #236)
Scaffold and pair install's expectations of KB repo shape drift apart over time	Low	Low	Scaffold reuses the same content-ops primitives as install/update, not a separate hand-rolled structure definition

Task Breakdown

Checklist

• T1 — Scaffold command: pure KB directory structure (.pair/knowledge/, .skills/), pair.config.json, README, .gitignore
• T2 — Release script/workflow generator that invokes pair package (tag, release, ZIP attachment)
• T3 — Idempotency handling (re-scaffold detection, confirm-before-overwrite on scaffold-owned files only)
• T4 — End-to-end round-trip test (scaffold → release → install) + docs site update

Dependency Graph

T1 → T2 → T3 → T4

AC Coverage

Task	AC1	AC2	AC3	AC4
T1	✓
T2		✓
T3				✓
T4			✓	✓