agent-profile-kit 0.204.1

package/docs/guides/agent-workflow.md

@@ -0,0 +1,127 @@
+# Agent Profile Kit agent workflow
+
+Use this workflow when helping a person author their Workspace and bind projects.
+
+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.
+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.
+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
+   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
+   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.”
+   - **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
+     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.
+   - **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
+     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,
+     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
+     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),
+   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,
+   per-session selection, and Profile version pins. Installing a different
+   Profile or Host 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
+   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
+   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
+   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
+   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`
+   and `.agent-profile-kit/opencode/context.md` and shared `.agents/skills/<Artifact ID>`
+   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
+   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
+   reports all-current state when nothing needs action, labels change
+   paths with `+`, `~`, `-`, or `!` markers, caps long lists with a pointer to
+   `--verbose`, explains non-current states when they appear, preserves warnings
+   and blockers, and ends with one next-action line when useful (run the matching
+   update for pending work; resolve a blocker and retry status when blocked; omit
+   when already current). Pending Git exclusion work appears as one concise clause.
+   A ready fleet `status --all` recommends `update --all`; blocked `status` or
+   `update` retries that command after the blocker. Add
+   `--verbose` to distinguish current, stale, drifted, missing, and blocked
+   installations and inspect exact Git exclusion paths in the complete report.
+   `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.
+   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.
+
+If the user plans to publish the Workspace, remind them to review personal
+content. Credentials are invalid in a Workspace regardless of publication
+visibility.