@ai-outfitter/outfitter 0.3.0

package/requirements/OFTR-005-run-and-composite-profile.md

@@ -0,0 +1,60 @@
+# OFTR-005: Run Command and Composite profile Lifecycle
+
+## Overview
+
+The `run` command assembles a temporary agent-specific configuration directory called a composite profile, launches the selected agent CLI, and keeps Outfitter alive to manage the composite profile while the child process runs.
+
+## Requirements
+
+### OFTR-005.1: Run Command Defaults
+
+1. Outfitter MUST provide a `run` command.
+2. `run` MUST be the default command when no command is specified.
+3. The default command behavior MUST be implemented with Commander rather than a custom `process.argv` parser.
+4. The `run` command MUST accept `-p` and `--profile` options for selecting the profile.
+5. The `run` command MUST use the resolved default profile when no profile option is provided.
+6. The `run` command MUST pass unrecognized arguments through to the selected agent CLI unaltered.
+7. When invoked before user setup has created `~/.outfitter/settings.yml`, the default `run` command MUST print `` `outfitter setup` has not been run yet - running now `` and execute setup before resolving the profile.
+
+### OFTR-005.2: Composite profile Definition
+
+1. Outfitter MUST call the dynamically assembled runtime configuration directory a `composite profile`.
+2. A composite profile MUST be scoped to a resolved profile and a selected agent CLI.
+3. Outfitter MUST create composite profile directories under the system temporary directory.
+4. Outfitter SHOULD use composite profile paths that include a run-specific identifier to avoid collisions between concurrent runs.
+
+### OFTR-005.3: Composite profile Assembly
+
+1. Outfitter MUST assemble the composite profile from resolved profile layers in precedence order.
+2. Outfitter MUST combine generic profile controls with CLI-specific overrides.
+3. Each logical generated file in the composite profile MUST have an object instance representing it.
+4. Each composite profile file object MUST know its source inputs and generated output path.
+5. Each composite profile file object SHOULD expose its merge or transform strategy.
+
+### OFTR-005.4: Composite profile Watching
+
+1. Outfitter MUST keep its process alive while the child agent CLI is running.
+2. Outfitter MUST use `fs.watch` or an equivalent Node file watching mechanism on composite profile input files while the child process is running.
+3. Outfitter MUST update generated composite profile files when watched inputs change and the generated output path remains inside the composite profile root.
+4. Outfitter MUST warn when a live update cannot be applied because regeneration or composite profile-root path validation fails.
+
+### OFTR-005.5: Unsupported Controls and Strict Mode
+
+1. Outfitter MUST write a warning to stderr when a profile requests a control that the selected agent adapter cannot support.
+2. The `run` command MUST accept a `--strict` option.
+3. When `--strict` is enabled, unsupported controls MUST cause composite profile assembly to fail instead of only warning.
+4. Strict failures MUST identify the unsupported control and selected agent CLI.
+
+### OFTR-005.6: Composite profile State Persistence
+
+1. Profiles MAY define `state_persistence` entries that map adapter-declared state paths to persistence strategies.
+2. Outfitter MUST validate `state_persistence` values at profile read boundaries.
+3. Before launch, Outfitter MUST resolve each adapter-declared state path to either a profile override strategy or the adapter default strategy.
+4. Outfitter MUST reject profile `state_persistence` keys that are not declared by the selected adapter.
+5. Outfitter MUST reject strategies that are not allowed for the adapter-declared state path.
+6. For `symlink` strategy paths, Outfitter MUST materialize the composite profile path as a symlink to the resolved profile or native CLI source path.
+7. For non-persistent strategies, Outfitter MUST materialize normal temporary composite profile paths and detect writes after the child agent exits.
+8. Unknown writes MUST be governed by the adapter's `unknown` pseudo-path strategy and MUST NOT be persisted by symlink.
+9. Outfitter MUST warn for `warn`, `prompt`, and symlink-replacement state write issues, fail for `error` state write issues, and ignore `discard` state writes.
+10. State path materialization MUST reject paths that escape the composite profile root.
+11. During live composite profile updates, Outfitter MUST update generated composite profile files without re-materializing declared state paths so post-launch write detection can still observe agent changes to those paths.

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

@@ -0,0 +1,64 @@
+# 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.
+
+### 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

@@ -0,0 +1,32 @@
+# 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

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,25 @@
+# OFTR-009: Release Publishing
+
+## Overview
+
+Outfitter release publishing prepares package metadata from a GitHub release tag and publishes the `@ai-outfitter/outfitter` npm package through GitHub Actions.
+
+## 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 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 publish the public `@ai-outfitter/outfitter` package to the npm registry using an npm token secret.

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

@@ -0,0 +1,38 @@
+# OFTR-010: Onboarding Welcome
+
+## Overview
+
+Outfitter welcome onboarding guides a new user through the minimum choices needed to start productive Pi sessions, including an initial role and a recommended loadout of extensions and skills.
+
+## Requirements
+
+### OFTR-010.1: Welcome Text
+
+1. Welcome text MUST be shown to the user explaining what Outfitter and Pi are.
+
+> Pi is a heavily customizable coding harness.
+> The next few questions will configure Outfitter to best suit your workflow.
+
+### OFTR-010.2: Role Selection
+
+1. The welcome onboarding flow MUST ask the user to choose an initial role for the Outfitter-managed agent session.
+2. Role choices MUST align with Outfitter's built-in standard role catalog, not DeepWork review personas or a remote default profile source.
+3. The role selection prompt MUST include the currently available built-in standard profile roles, including `engineer` and `data_analyst` while those roles remain supported.
+4. The selected role MUST be captured as structured onboarding data so profile creation or profile selection can map it to the matching standard profile ID.
+5. If the selected role cannot be mapped to an available standard profile for the selected agent adapter, Outfitter MUST warn the user and choose a deterministic fallback role rather than silently ignoring the selection.
+
+### OFTR-010.3: Loadout Selection
+
+1. The welcome onboarding flow MUST recommend at least one default loadout for the selected role.
+2. A loadout MUST be represented as a named set of Pi extensions, skills, or package resources that Outfitter can translate into profile controls or profile-managed Pi configuration.
+3. The welcome onboarding flow MUST allow the user to accept the recommended loadout, select individual loadout items, or skip loadout installation.
+4. The default recommended loadout MUST include `git:github.com/ai-outfitter/ulta-tasklist`, `git:github.com/ai-outfitter/deepwork`, `npm:pi-subagents`, and `npm:pi-mcp-adapter` while those packages remain available.
+5. Loadout installation MUST be captured as structured onboarding data so future profile creation can install the selected extensions, skills, or package resources deterministically.
+6. If a loadout item is unavailable or unsupported by the selected agent adapter, Outfitter MUST warn the user and continue with the remaining selected loadout items unless strict onboarding validation is enabled.
+
+### 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.

package/src/schemas/SchemaDocument.ts

@@ -0,0 +1,20 @@
+// Defines named JSON Schema document metadata for Outfitter persisted formats.
+export interface SchemaDocument {
+  readonly id: string;
+  readonly path: string;
+}
+
+export const settingsSchemaDocument: SchemaDocument = {
+  id: 'settings',
+  path: 'src/schemas/settings.schema.json',
+};
+
+export const profileSchemaDocument: SchemaDocument = {
+  id: 'profile',
+  path: 'src/schemas/profile.schema.json',
+};
+
+export const profileSourceSchemaDocument: SchemaDocument = {
+  id: 'profile-source',
+  path: 'src/schemas/profile-source.schema.json',
+};

package/src/schemas/profile-source.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://outfitter.dev/schemas/profile-source.schema.json",
+  "title": "Outfitter profile source",
+  "type": "object",
+  "oneOf": [
+    {
+      "required": ["path"],
+      "not": { "anyOf": [{ "required": ["uri"] }, { "required": ["github"] }, { "required": ["ref"] }] }
+    },
+    { "required": ["uri"], "not": { "required": ["github"] } },
+    { "required": ["github"], "not": { "required": ["uri"] } }
+  ],
+  "properties": {
+    "path": { "type": "string", "minLength": 1 },
+    "uri": { "type": "string", "minLength": 1 },
+    "github": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" },
+    "ref": { "type": "string", "minLength": 1 },
+    "only": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "except": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "additionalProperties": false
+}

package/src/schemas/profile.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://outfitter.dev/schemas/profile.schema.json",
+  "title": "Outfitter profile",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$|^[a-z0-9]$"
+    },
+    "label": { "type": "string" },
+    "inherits": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9._-]*[a-z0-9]$|^[a-z0-9]$"
+      }
+    },
+    "state_persistence": {
+      "type": "object",
+      "additionalProperties": {
+        "enum": ["symlink", "discard", "warn", "error", "prompt"]
+      }
+    },
+    "controls": {
+      "type": "object",
+      "properties": {
+        "model": { "type": "string" },
+        "provider": { "type": "string" },
+        "thinking": { "type": "string" },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "session_directory": { "type": "string" },
+        "extensions": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "skills": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "prompt_template": { "type": "string" },
+        "system_prompt": { "type": "string" },
+        "append_system_prompt": { "type": "string" },
+        "environment": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "pi": {
+          "type": "object",
+          "properties": {
+            "model": { "type": "string" },
+            "provider": { "type": "string" },
+            "thinking": { "type": "string" },
+            "args": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "session_directory": { "type": "string" },
+            "extensions": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "skills": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "prompt_template": { "type": "string" },
+            "system_prompt": { "type": "string" },
+            "append_system_prompt": { "type": "string" },
+            "allow_external_deepwork_jobs": { "type": "boolean" },
+            "environment": {
+              "type": "object",
+              "additionalProperties": { "type": "string" }
+            }
+          },
+          "additionalProperties": true
+        },
+        "claude": {
+          "type": "object",
+          "properties": {
+            "model": { "type": "string" },
+            "provider": { "type": "string" },
+            "thinking": { "type": "string" },
+            "args": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "session_directory": { "type": "string" },
+            "extensions": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "skills": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "prompt_template": { "type": "string" },
+            "system_prompt": { "type": "string" },
+            "append_system_prompt": { "type": "string" },
+            "environment": {
+              "type": "object",
+              "additionalProperties": { "type": "string" }
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/src/schemas/settings.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://outfitter.dev/schemas/settings.schema.json",
+  "title": "Outfitter settings",
+  "type": "object",
+  "properties": {
+    "default_profile": { "type": "string", "minLength": 1 },
+    "default_agent": { "enum": ["pi", "claude"] },
+    "cache_directory": { "type": "string", "minLength": 1 },
+    "profile_sources": {
+      "type": "array",
+      "items": { "$ref": "profile-source.schema.json" }
+    },
+    "remote_settings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "oneOf": [
+          { "required": ["uri", "path"], "not": { "required": ["github"] } },
+          { "required": ["github", "path"], "not": { "required": ["uri"] } }
+        ],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "uri": { "type": "string", "minLength": 1 },
+          "github": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" },
+          "ref": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "custom_settings": {
+      "type": "object",
+      "description": "Arbitrary YAML-compatible values exposed to Outfitter compositeProfile templates as outfitter.custom_settings."
+    }
+  },
+  "additionalProperties": true
+}