agent-profile-kit 0.204.1 → 0.237.1

package/docs/guides/agent-workflow.md

@@ -1,98 +1,139 @@
 # Agent Profile Kit agent workflow
 
-Use this workflow when helping a person author their Workspace and bind projects.
+Use this workflow when helping a person set up Agent Profile Kit, migrate their existing Skills and instructions into a Workspace, compose Profiles, and bind projects.
+
+## Fast-start onboarding & migration playbook
+
+When a user points you at this repository or asks you to set up Agent Profile Kit from scratch, execute these five steps non-interactively (confirming user choices before writing):
+
+1. **Run `apkit` without requiring manual CLI setup.**
+   Check whether `apkit` is on `PATH` (`command -v apkit`). If not, invoke it via `npx --yes --package agent-profile-kit apkit <command>`. Always pass explicit paths, and pass `--auto-confirm` to the commands that confirm (`install`, `uninstall`, and `configure profile`) so they never hang waiting for a terminal prompt. `init`, `new`, `validate`, `status`, and `update` take no confirmation flag: run without a terminal, they never prompt, and a supplied `init` path counts as confirmation. Optionally offer to add `alias apkit="npx --yes --package agent-profile-kit apkit"` to `~/.zshrc` if the user wants a short command for themselves.
+2. **Initialize or connect the Workspace.**
+   Check `~/.agents/agent-profile-kit/config.yaml` first. If no Workspace is configured, ask the user where they want their Workspace (suggest `~/agent-profile-workspace` or `~/projects/agent-profile-workspace`) and run `apkit init <workspace>`.
+3. **Discover and migrate existing Skills and instruction files.**
+   Scan the user's machine for existing reusable material they may want to bring into their Workspace:
+   - Global agent directories: `~/.claude/CLAUDE.md`, `~/.claude/skills/`, `~/.claude/commands/`, `~/.agents/AGENTS.md`, `~/.agents/skills/`, `~/.agents/rules/`, `~/.codex/AGENTS.md`, `~/.codex/skills/`, `~/.grok/GROK.md`, `~/.grok/skills/`.
+   - Current project directories (if inside a repo): `CLAUDE.md`, `AGENTS.md`, `.claude/skills/`, `.claude/rules/`, `.agents/skills/`, `.agents/rules/`.
+   Present a concise summary of what you found and ask which items are reusable across projects (versus repo-specific facts that should stay in the repo). Then **copy** (never delete the user's originals):
+   - Reusable instruction files into `<workspace>/context/<kebab-case-id>.md` (plain Markdown, no frontmatter needed; nested folders like `context/engineering/testing.md` become ID `engineering/testing`).
+   - Reusable Skill folders into `<workspace>/skills/<skill-name>/SKILL.md` (must start with YAML frontmatter containing `name: <skill-name>` matching the folder name and a non-empty `description:`).
+4. **Create the first Profile and validate.**
+   Ask what Profile name fits their workflow (for example `engineering`, `creator`, or `default`), then run:
+   ```sh
+   apkit new profile <profile> --context <id>... --skill <id>...
+   apkit validate
+   ```
+   (Use `apkit configure profile <profile> --context <id>... --skill <id>... --auto-confirm` when updating an existing Profile's full membership list.)
+5. **Install into the user's projects.**
+   Ask which project directory (or directories) and which agents (`claude`, `codex`, `antigravity`, `grok`, `opencode`, `pi`) they want to bind. Before running `install` on a Git repository, check whether the planned agent output paths (for example `.claude/rules/agent-profile-kit.md`, `.agents/skills/<skill>`, or `.agent-profile-kit/`) are already git-tracked in that repo; if so, warn the user about the Output Ownership Conflict before proceeding. Then run:
+   ```sh
+   apkit install <profile> <project-path> --agent <agent> --auto-confirm
+   apkit status
+   ```
+
+---
+
+## Core rules and lifecycle reference
 
 1. Read this guide first. Then inspect the Workspace: start with `workspace.yaml`
-   and its schema version. A valid Workspace needs only that Manifest; missing
-   artifact directories are empty categories, and bootstrap files such as
-   `README.md`, `AGENTS.md`, and `.gitignore` are optional scaffolding from
-   `init`, not format requirements. Use `apkit init` for the fixed
-   default or `apkit init <workspace>` for one explicit absolute or
-   home-relative destination; missing and empty non-symlink destinations are
-   scaffolded, while valid existing Workspaces are adopted without source
-   changes. Inspect any present artifact directories next. Treat the Workspace
-   as the canonical source; do not infer reusable material from generated Host
-   output.
+   and its schema version. The Workspace contract (run `apkit guide --contract`)
+   states the required structure and every rule `apkit validate` enforces; in
+   short, a valid Workspace has the `workspace.yaml` Manifest plus the
+   `context/`, `skills/`, and `profiles/` directories, which `apkit init` adds
+   when missing; missing artifact directories are empty collections, and
+   bootstrap files such as `README.md`, `AGENTS.md`, and `.gitignore` are
+   optional user-owned files, not format requirements. There is no default
+   Workspace location: use `apkit init <workspace>` for one explicit
+   destination (`.` uses the current folder); setup adds exactly the missing
+   required parts in place and never touches other entries, while a folder
+   whose existing material is invalid is refused with its violation
+   (spec #593 DEC-003, ADR-0047, ADR-0049). Inspect any present
+   artifact directories next. Treat the Workspace as the canonical source; do
+   not infer reusable material from generated agent output.
 2. Elicit the user's needs one decision at a time. Establish the kind of work,
    the reusable facts or workflow they want, and whether existing material
    already satisfies the need. Ask instead of inventing personal preferences,
-   project facts, Host preferences, credentials, or machine paths.
+   project facts, agent preferences, credentials, or machine paths.
 3. Create the smallest useful artifact set. This release accepts Profile Context
    and shared Skills for Antigravity, plus portable Context and Skills for Codex,
    Claude Code, Grok, OpenCode, and Pi. Put standing facts in
-   Context Modules and reusable procedures in Skills. A Profile needs at least
+   Context Modules and reusable procedures in Skills. Author each artifact to
+   the Workspace contract, which states every rule validation enforces —
+   Context Module identity and delivery, the Skill
+   package rules including the standard `disable-model-invocation` field, and
+   the Profile shape (file name is the ID; the file holds exactly `context`
+   and `skills`). A Profile needs at least
    one supported artifact (Context, Skills, or both); Context is not mandatory—a
-   Skills-only Profile is valid. For Skills that must not fire implicitly, use
-   `metadata.agent-profile-kit.model-invocation: disabled` (default is
-   `allowed`); do not leave Host-native `disable-model-invocation` in
-   Workspace source (Adapters project that field for Claude, Grok, and Pi). Profiles
-   contain exactly `id`, `context`, and `skills`. Do not create a new artifact merely because
+   Skills-only Profile is valid. Do not create a new artifact merely because
    a directory exists, and do not invent Agents, Hooks, or Tools
    for this release.
 4. Preserve boundaries.
    - **Workspace** owns reusable cross-project Profiles and artifacts as the
      single canonical source. That includes Profile-selected material and
      unselected universal artifacts (useful across every directory or kind of
-     work). Unselected does not mean “belongs in Host config.”
+     work). Unselected does not mean “belongs in agent config.”
    - **Local Configuration** (`~/.agents/agent-profile-kit/config.yaml`) owns
      machine-local Project Bindings and the explicit Workspace path. Current
      schema version 2 requires one existing absolute or home-relative Workspace
      path and each binding names one existing project root, one Profile, and a
-     supported Host set (`antigravity`, `codex`, `claude`, `grok`, `opencode`, or `pi`); Host
+     supported agent set (`antigravity`, `codex`, `claude`, `grok`, `opencode`, or `pi`); agent
      order and duplicate entries normalize at ingestion. A version-1 configuration without
-     `workspace` is legacy migration input only; run `apkit init` before any desired-state
-     or binding-recording command.
+     `workspace` is legacy migration input only; run `apkit init <path>` before any desired-state
+     or binding-recording command (ADR-0049).
    - **Project repositories** own project facts and repository-owned instructions.
-   - **Hosts** own authentication, trust, approvals, plugins, sessions, and
-     Host preferences. User-managed native global Skill delivery (including
-     Host-root symlinks into Workspace source) is Host configuration, not
+   - **Agents** own authentication, trust, approvals, plugins, sessions, and
+     agent preferences. User-managed native global Skill delivery (including
+     agent-root symlinks into Workspace source) is agent configuration, not
      Agent Profile Kit–owned state: outside Project Bindings and Installation
      Manifests; `update` / `uninstall` never adopt or remove those paths. v1 does
-     not manage global Host delivery. Hosts own Skill discovery, precedence,
+     not manage global agent delivery. Agents own Skill discovery, precedence,
      deduplication, collision diagnostics, and resolution across project,
      personal, package, plugin, extension, and compatibility sources.
    - **Generated output** is disposable Installer-owned material inside bound
      projects. Never copy it back into the Workspace as source.
    - Same-identity Skill material outside an exact planned output destination is
-     Host Resolution, not an Agent Profile Kit blocker. Concrete Host settings
+     agent resolution, not an Agent Profile Kit blocker. Concrete agent settings
      that disable planned output may warn; exact Output Ownership Conflicts and
      unsupported capability remain blockers.
 5. Install Profiles into Projects—either hand-edit `config.yaml` and run
-   `apkit update`, or run `apkit install <profile> [project] --host <host>…`
-   (cwd when project is omitted; at least one explicit `--host` required),
+   `apkit update`, or run `apkit install <profile> [project] --agent <agent>…`
+   (cwd when project is omitted; at least one explicit `--agent` required),
    which records the selection and installs the verified output in one
    action after an interactive confirmation (`--auto-confirm` answers it
    non-interactively). Do not
-   invent project roots or Host lists. Use only explicit paths the user confirms.
-   Reject wildcards, recursive scans, Host auto-detection, all-Hosts defaults,
+   invent project roots or agent lists. Use only explicit paths the user confirms.
+   Reject wildcards, recursive scans, agent auto-detection, all-agents defaults,
    per-session selection, and Profile version pins. Installing a different
-   Profile or Host set for the same project replaces the installation in the
+   Profile or agent set for the same project replaces the installation in the
    same action; replacing or deleting independently changed generated files
    needs `--replace-changed`/`--remove-changed`. After installing, continue
    with validate/status/update. To remove selected installations, use
    `apkit uninstall --here`, `uninstall --project <path>`, or `uninstall --all`
    (explicit scope plus `--auto-confirm` non-interactively, with `--profile`,
-   `--host`, and `--remove-changed` as needed); it forgets each fully removed Project's
+   `--agent`, and `--remove-changed` as needed); it forgets each fully removed Project's
    recorded selection so a later update does not reinstall it, matches
    existing paths canonically, and permits missing-path recovery only by exact
    authored spelling. To keep generated files in place instead, remove the
    Project's entry from Local Configuration by hand and let the next update
    reconcile the leftovers.
-6. Validate before updating. Context Modules use `id` frontmatter and flat
-   Profiles contain `id`, `context`, and `skills` only. Dependencies use
-   explicit `{ type, id }` references. Run `apkit validate`, review
+6. Validate before updating. Context Modules are plain Markdown files whose
+   path under `context/` (without `.md`) is their ID, and
+   Profiles are named by their file name and contain `context` and `skills`
+   only; the Profile lists are
+   the only source of what is installed (no Dependencies, no sidecar files).
+   Run `apkit validate`, review
    the concise fleet outcome from `apkit status --all`, and ask before updating
    all configured Project Bindings with `apkit update --all`. Use Project-scoped
    `update [project]` only when the user intends one bound Project. Use
    `apkit status --verbose` or `apkit update --verbose` when complete
-   per-output diagnostics, resolved artifact reasons, or composed Context are
-   needed. For automation, add `--json` on those two commands: exit `0` means
+   per-output diagnostics or composed Context are needed. For automation, add
+   `--json` on those two commands: exit `0` means
    no tool error and no blockers (JSON `outcome` may still be `attention`),
    exit `1` is a tool error, and exit `2` means blockers. The current Workspace
    schema version is 1.
 7. After update, the user launches Antigravity, Codex, Claude, Grok, OpenCode, or Pi
    natively in the bound project. Do not claim that Agent Profile Kit manages
-   Host authentication, trust, approvals, plugins, or sessions. Antigravity
+   agent authentication, trust, approvals, plugins, or sessions. Antigravity
    bindings load deterministic always-on Context rules under `.agents/rules/`
    and shared `.agents/skills/<Artifact ID>` packages after the user's native
    trust step. OpenCode bindings load Profile Context via `.opencode/opencode.jsonc`
@@ -100,7 +141,10 @@ Use this workflow when helping a person author their Workspace and bind projects
    packages after restarting running sessions. Pi bindings load the generated
    `.pi/APPEND_SYSTEM.md` and shared `.agents/skills/<Artifact ID>` packages after
    Pi's native trust boundary; packages, extensions, and other Skill sources coexist
-   through Pi Host Resolution. For non-Git projects, remind the user that Codex must
+   through Pi agent resolution. Grok bindings load the generated `.grok/rules/` rule
+   (or Claude's shared rule when Claude is co-selected and Grok's Claude rules
+   compatibility is on) and `.grok/skills/<Artifact ID>`
+   packages after Grok's native folder trust. For non-Git projects, remind the user that Codex must
    launch from the exact bound root.
 8. Use `apkit status` for the bound Project containing cwd, pass one explicit
    Project root, or use `apkit status --all` for the fleet. Its concise result
@@ -117,7 +161,7 @@ Use this workflow when helping a person author their Workspace and bind projects
    `apkit uninstall` with an explicit scope removes only output whose Installation Receipt
    and hashes prove Agent Profile Kit ownership and forgets each fully removed
    Project's recorded selection; it preserves the Workspace,
-   unselected Projects, global Host configuration, and repository-owned files.
+   unselected Projects, global agent configuration, and repository-owned files.
    Never use hand-editing as a substitute for output cleanup: hand-editing the
    selection out of Local Configuration keeps generated files in place for the
    next update to reconcile, while `uninstall` deletes them.