@ai-outfitter/outfitter 0.6.1 → 0.7.1

package/requirements/OFTR-006-agent-adapters.md

@@ -1,66 +0,0 @@
-# OFTR-006: Agent Adapters, Pi Support, and Claude Code Support
-
-## Overview
-
-Agent adapters translate generic Outfitter profile controls into native configuration files, environment variables, and command-line arguments for specific agent CLIs.
-Pi is the default and primary supported adapter; Claude Code is also supported through a dedicated adapter.
-
-## Requirements
-
-### OFTR-006.1: Adapter Boundary
-
-1. Outfitter MUST define an agent adapter abstraction for CLI-specific composite profile assembly and launch command generation.
-2. Each adapter MUST expose an identifier for the agent CLI it supports.
-3. Each adapter MUST report which controllable elements it supports.
-4. Each adapter MUST return warnings for profile controls it cannot translate.
-5. Outfitter SHOULD keep generic profile resolution independent from adapter-specific file generation.
-
-### OFTR-006.2: Supported Adapter Availability
-
-1. Outfitter MUST support the `pi` agent CLI on day one.
-2. Outfitter MAY document other agent CLIs as roadmap adapters before implementing them.
-3. Non-pi adapters MUST NOT be presented as supported until their adapter implementation and tests exist.
-4. When generic Outfitter terminology conflicts with pi terminology, the pi adapter SHOULD prefer pi naming for generated pi artifacts and user-facing pi diagnostics.
-5. Outfitter MUST keep `pi` as the default adapter when no adapter is selected explicitly or through settings.
-6. Outfitter MUST support Claude Code through a `claude` adapter once implementation and tests are present.
-
-### OFTR-006.3: Pi Launch Controls
-
-1. The pi adapter MUST use `PI_CODING_AGENT_DIR` as the primary profile-scoped pi configuration boundary.
-2. The pi adapter MUST support profile-controlled environment variables.
-3. The pi adapter MUST support profile-controlled pi CLI arguments.
-4. The pi adapter SHOULD support `PI_CODING_AGENT_SESSION_DIR` or `--session-dir` for session location control.
-5. The pi adapter SHOULD support `--extension` or `-e` for explicit extension injection.
-6. The pi adapter SHOULD support `--skill` for explicit skill injection.
-7. The pi adapter SHOULD support `--prompt-template` for prompt template injection.
-8. The pi adapter SHOULD support `--system-prompt` and `--append-system-prompt` for prompt control.
-9. The pi adapter SHOULD support pi model, provider, and thinking controls where native pi flags exist.
-10. The pi adapter MUST merge `.mcp.json` files from contributing `cli_specific/pi/` profile folders into the composite profile, adding unique array entries by identity while keeping the last entry for duplicate identities.
-11. The pi adapter MUST make native Pi `models.json` available inside the composite profile so custom providers and model definitions are visible before Pi resolves `--provider` and `--model` flags.
-12. The pi adapter MUST expose valid Agent Skills from contributing profile `skills/` folders as `--skill` arguments, and MAY also expose Pi-specific skills from `cli_specific/pi/skills/`.
-13. The pi adapter MUST expose DeepWork jobs from contributing profile `deepwork/jobs/` folders through `DEEPWORK_ADDITIONAL_JOBS_FOLDERS`, and MAY also expose Pi-specific jobs from `cli_specific/pi/deepwork/jobs/`.
-
-### OFTR-006.4: Pi Startup Boundary
-
-1. Outfitter MUST NOT rely on pi extensions to choose the initial pi configuration directory.
-2. Outfitter MUST choose pi configuration paths before launching pi.
-3. Outfitter MAY use explicit bootstrap extensions for behavior that can run after pi has discovered its initial configuration directory.
-4. Outfitter MUST document warnings when a requested pi control cannot be applied because pi startup order makes it impossible.
-
-### OFTR-006.5: Claude Code Launch Controls
-
-1. The Claude Code adapter MUST use `CLAUDE_CONFIG_DIR` as the primary profile-scoped Claude Code configuration boundary.
-2. The Claude Code adapter MUST launch the native `claude` command.
-3. The Claude Code adapter MUST support profile-controlled environment variables.
-4. The Claude Code adapter MUST support profile-controlled pass-through Claude Code CLI arguments.
-5. The Claude Code adapter SHOULD support `--model`, `--effort`, `--system-prompt`, `--append-system-prompt`, and `--plugin-dir` where native Claude Code flags exist.
-6. The Claude Code adapter SHOULD support `controls.session_directory` and `controls.claude.session_directory` by routing Claude `projects/` session state through Outfitter state persistence.
-7. The Claude Code adapter MUST return unsupported-control warnings for requested generic or `controls.claude` controls that it cannot translate.
-
-### OFTR-006.6: Pi Settings Reconciliation
-
-1. When profile-controlled Pi extensions duplicate native Pi `settings.json` package entries, the pi adapter MUST avoid launching pi with both copies enabled.
-2. The pi adapter MUST compare duplicate Pi extension and package entries by normalized resource identity rather than raw source string.
-3. The pi adapter MUST preserve unrelated Pi settings and unrelated package entries when generating a reconciled runtime `settings.json`.
-4. The pi adapter MUST keep reconciled runtime `settings.json` writes non-durable and declared so they are discarded without being reported as unknown state.
-5. The pi adapter MUST fall back to native Pi `settings.json` state persistence when reconciliation is unnecessary or the settings file cannot be interpreted safely.

package/requirements/OFTR-007-controllable-elements.md

@@ -1,32 +0,0 @@
-# OFTR-007: Controllable Elements Documentation
-
-## Overview
-
-Outfitter maintains a generic cross-agent-CLI vocabulary for profile-controlled concepts.
-This vocabulary is documented separately from implementation details so companies can reason about profiles across multiple agent CLIs.
-
-## Requirements
-
-### OFTR-007.1: Documentation File
-
-1. The project MUST include documentation with the header `Controllable Elements`.
-2. The controllable elements documentation MUST define each generic controllable aspect as a named term.
-3. Each defined term MUST describe the equivalent name or mechanism for pi.
-4. Each defined term SHOULD describe the equivalent name or mechanism for other major CLIs when those mappings are known.
-
-### OFTR-007.2: Support Matrix
-
-1. The controllable elements documentation MUST include a support matrix table.
-2. The support matrix MUST contain one row for each defined controllable aspect.
-3. The support matrix MUST contain one column for each documented agent CLI.
-4. Each support matrix cell MUST contain exactly one of `Unsupported`, `Supported`, or `Roadmap`.
-5. Pi MUST be the only CLI with `Supported` entries until another adapter is implemented and tested.
-
-### OFTR-007.3: Initial Controllable Aspects
-
-1. The documentation MUST include an Agent Config Directory controllable element.
-2. The documentation MUST include a Session Directory controllable element.
-3. The documentation MUST include Extensions, Skills, and Prompt Templates controllable elements.
-4. The documentation MUST include System Prompt and Appended System Prompt controllable elements.
-5. The documentation MUST include Model Selection and Credentials and Environment controllable elements.
-6. The documentation MUST include Tool Availability, Context Files, Theme or UI Presentation, Project Override Policy, Working Directory, Pass-through Arguments, and Bootstrap Hook controllable elements.

package/requirements/OFTR-008-requirements-governance.md

@@ -1,42 +0,0 @@
-# OFTR-008: Requirements Governance
-
-## Overview
-
-Outfitter requirements define reviewable project obligations.
-Each requirement should be traceable to TypeScript implementation, tests, DeepSchemas, or DeepReview rules depending on the appropriate validation mechanism.
-
-## Requirements
-
-### OFTR-008.1: Requirement File Format
-
-1. Requirement files MUST live under `requirements/` and use filenames matching `OFTR-NNN-<topic>.md`.
-2. Requirement files MUST begin with a top-level heading matching `# OFTR-NNN: Title`.
-3. Requirement files MUST include an `## Overview` section before requirements.
-4. Requirement files MUST include an `## Requirements` section.
-5. Requirement section headings MUST use the format `### OFTR-NNN.M: Title`.
-6. Requirement statements MUST use RFC 2119 keywords such as MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, REQUIRED, RECOMMENDED, or OPTIONAL.
-7. Requirement section ID numbering within each file MUST be sequential without gaps.
-8. Each requirement MUST be specific enough to verify by automated test, DeepSchema, DeepReview rule, or direct reviewer judgment.
-
-### OFTR-008.2: Validation Mechanism Selection
-
-1. Machine-verifiable requirements MUST be validated by automated TypeScript tests when the implementation exists.
-2. Single-file semantic requirements SHOULD be validated by anonymous DeepSchemas placed next to the governed file.
-3. Broad judgment-based requirements SHOULD be validated by `.deepreview` rules.
-4. Tests MUST NOT use fragile keyword checks to pretend to validate judgment-based requirements.
-5. Review rules SHOULD NOT ask reviewers to verify exact values, paths, or schema shapes that an automated test or JSON Schema can verify deterministically.
-
-### OFTR-008.3: Test Traceability Comments
-
-1. Tests that validate a formal requirement MUST include a traceability comment immediately before the test case or test block.
-2. Traceability comments MUST identify at least one requirement ID using the pattern `OFTR-NNN.M`.
-3. Traceability comments MUST state that the test validates a hard requirement and MUST NOT be modified unless the requirement changes.
-4. Test comments MUST describe durable behavior or policy intent rather than transient line numbers, pull request numbers, or current-diff context.
-5. Test comments MUST be updated or removed when the tested behavior changes.
-
-### OFTR-008.4: Traceability Reviews
-
-1. Changes to requirement files MUST trigger review of requirement formatting and traceability.
-2. Changes to TypeScript source or tests SHOULD trigger review for missing requirement coverage when they introduce or change product behavior.
-3. Changes to DeepSchemas or `.deepreview` policies MUST preserve references to the requirement IDs they enforce when applicable.
-4. The requirements DeepSchema MUST include a filename regex that matches the `OFTR-NNN-<topic>.md` naming style.

package/requirements/OFTR-009-release-publishing.md

@@ -1,35 +0,0 @@
-# OFTR-009: Release Publishing
-
-## Overview
-
-Outfitter release publishing prepares package metadata from Conventional Commit release PRs and GitHub release tags, then publishes the `@ai-outfitter/outfitter` npm package through GitHub Actions using npm trusted publishing / OIDC.
-
-## Requirements
-
-### OFTR-009.1: Release Metadata Synchronization
-
-1. The release metadata synchronization script MUST accept a release version from an explicit argument, `OUTFITTER_RELEASE_VERSION`, or `GITHUB_REF_NAME`, in that precedence order.
-2. The release metadata synchronization script MUST normalize a leading `v` from release tags before writing package metadata.
-3. The release metadata synchronization script MUST reject invalid Semantic Versioning values before mutating package metadata.
-4. The release metadata synchronization script MUST update the root `package.json` version, root `package-lock.json` version, and `package-lock.json` root package entry version to the same normalized release version.
-5. The release metadata synchronization script MUST verify that the root package metadata it prepares belongs to the `@ai-outfitter/outfitter` npm package.
-6. The release metadata synchronization script MUST verify that `package.json` and the package-lock root metadata declare `repository.url` as `https://github.com/ai-outfitter/outfitter.git` so npm provenance validation can match the publishing repository.
-7. The release metadata synchronization script MUST fail with an actionable error when required package-lock root package metadata is missing.
-
-### OFTR-009.2: Npm Release Workflow
-
-1. The npm release workflow MUST run when a GitHub release is published.
-2. The npm release workflow MUST install dependencies with `npm ci` before publishing.
-3. The npm release workflow MUST synchronize package metadata from the GitHub release tag before publishing.
-4. The npm release workflow MUST run CI checks before publishing.
-5. The npm release workflow MUST build the package before publishing.
-6. The npm release workflow MUST request `id-token: write`, use the `npm-publish` GitHub environment, and publish the public `@ai-outfitter/outfitter` package to the npm registry with provenance through npm trusted publishing / OIDC rather than `NPM_TOKEN` or `NODE_AUTH_TOKEN`.
-
-### OFTR-009.3: Conventional Commit Release Automation
-
-1. The Release Please workflow MUST run on pushes to `main`.
-2. The Release Please workflow MUST use `googleapis/release-please-action@v4` with the upstream example-style token input from `secrets.RELEASE_PLEASE_TOKEN`.
-3. The Release Please workflow MUST use `release-type: node` for the root `@ai-outfitter/outfitter` npm package.
-4. The Release Please workflow MUST derive version bumps from Conventional Commits.
-5. The Release Please workflow MUST update npm package metadata and changelog through a release PR before publishing.
-6. The Release Please workflow MUST use GitHub repository write auth capable of triggering release PR CI and the release-published npm workflow, not the default `GITHUB_TOKEN`.

package/requirements/OFTR-010-onboarding-welcome.md

@@ -1,48 +0,0 @@
-# OFTR-010: Onboarding Welcome
-
-## Overview
-
-Outfitter welcome onboarding gets a new user to a productive Pi session in one question. The
-recommended path installs the founder profile automatically; declining opens `/outfitter` inside Pi
-so the user can configure a profile interactively.
-
-## Requirements
-
-### OFTR-010.1: Welcome Text
-
-1. Welcome text MUST be shown to the user explaining what Outfitter and Pi are and what the founder profile provides.
-2. Welcome text MUST use Outfitter-branded ASCII/text.
-3. Welcome text MUST reference `/outfitter` as the way to customize the profile after installation.
-
-> Pi is a fully extensible agentic coding harness.
-> The founder profile brings Pi to feature parity with dedicated agentic coding tools.
-> Press Y to install it now. Run /outfitter inside Pi at any time to customize your profile.
-
-### OFTR-010.2: Profile Installation
-
-1. The welcome onboarding flow MUST present a single accept/decline prompt for the founder profile.
-2. Accepting (default) MUST install the founder role and the full recommended loadout without further prompts.
-3. The founder role MUST be the default and fallback selection. Outfitter's built-in role catalog also includes `engineer` and `data_analyst`; these are accessible via `/outfitter` after first run.
-4. If the accepted role cannot be mapped to an available standard profile, Outfitter MUST warn the user and choose a deterministic fallback role rather than silently ignoring the selection.
-
-### OFTR-010.3: Loadout
-
-1. On acceptance, the full recommended loadout MUST be installed automatically with no item-level selection prompt.
-2. The default recommended loadout MUST include `git:github.com/ai-outfitter/deepwork`, `npm:@juicesharp/rpiv-ask-user-question`, `git:github.com/applepi-ai/ulta-tasklist`, `npm:pi-nolo`, `npm:pi-browser-harness`, `npm:@mjakl/pi-subagent`, `npm:@narumitw/pi-btw`, `npm:pi-must-have-extension`, `npm:pi-interactive-shell`, and `npm:pi-mcp-adapter` while those packages remain available.
-3. Loadout installation MUST be captured as structured onboarding data so profile creation can install the selected extensions deterministically.
-4. On acceptance, Outfitter MUST display a message directing users to `/outfitter` inside Pi and `outfitter profile list` in the terminal for post-install management.
-5. If a loadout item is unavailable or unsupported by the selected agent adapter, Outfitter MUST warn the user and continue with the remaining loadout items unless strict onboarding validation is enabled.
-6. The Outfitter npm package MUST publish a default Pi skill named `outfitter` for profile setup guidance from inside Pi.
-7. The Pi adapter MUST load the default Outfitter skill for normal profile launches.
-
-### OFTR-010.4: Pi Login Setup
-
-1. Before launching Pi after the welcome flow, Outfitter MUST detect whether native Pi appears to have no configured login state.
-2. If Pi is not logged in after the welcome flow, Outfitter MUST automatically invoke Pi's `/login` flow when Pi starts.
-3. When Outfitter launches Pi outside the welcome flow and Pi does not appear to be logged in, Outfitter MUST inform the user to run `/login` inside Pi.
-4. Pi login setup MUST NOT ask Outfitter to collect, echo, or persist provider API keys.
-
-### OFTR-010.5: Decline Path
-
-1. If the user declines the welcome profile, Outfitter MUST launch Pi with `/outfitter` prefilled and auto-submitted so the user can configure a profile interactively on first session start.
-2. The profile install target MUST always be the user home directory (`~/.outfitter`); no installation scope prompt MUST be shown.