@refactco/refact-os 1.5.0

package/templates/base/agent/skills/refact/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: refact
+description: Single entrypoint skill for refact-os project operations. Use when the user invokes /refact with an action like updating the package, importing chat history, or running project-type setup flows.
+pattern: orchestrator
+when_to_use: The user types /refact <action> — init, update the package, get chat history, process docs, status, git it, install wp skills, add codebase, sync asana, setup kinsta, wp-env operations, setup nextjs app, setup vercel deploy, or setup netlify deploy.
+when_not_to_use: For code changes (use code-development) or for capturing a learning (use extract-learnings).
+disable-model-invocation: true
+next_skills:
+  - setup-project
+  - update-package
+  - import-chat-history
+  - process-docs
+  - project-status
+  - git-it
+  - sync-asana
+sub_agents: []
+---
+
+# Refact Skill
+
+Use this skill as a command router for `/refact ...` requests.
+
+## Preflight: required scaffold metadata
+
+Every `/refact ...` invocation passes through the `preflight-metadata` Cursor hook (registered on `beforeSubmitPrompt` in `.cursor/hooks.json`). The hook reads `.refact-os.json` at the project root and checks that every **required** field is present. Optional fields never block — the hook ignores them whether they are set, `null`, or absent.
+
+Fields (kept in sync between `lib/refact-config.js` in the package and `.cursor/hooks/preflight-metadata.mjs` in the project):
+
+| Path | Required | Notes |
+|---|---|---|
+| `stack` | yes | Object keyed by project type — **its keys are the type list** (`wordpress`, `nextjs`, `blank`); at least one. Each entry holds `hosting`, `runtime`, and `environments` (per-env `url` / `branch` / optional `ssh`). There is no separate `projectType`/`projectTypes`. |
+| `asana.projectId` | no (optional) | Numeric ID from `https://app.asana.com/0/<id>/...`. The gate never blocks on it — set it (or run `/refact sync asana`) when you start using Asana; otherwise leave it unset or `null`. |
+
+If the hook detects a missing **required** field it blocks the prompt and returns a message listing them. When that happens:
+
+1. Ask the user for each missing value, one focused question at a time.
+2. Write the answers into `.refact-os.json` (create the file if it doesn't exist).
+3. Tell the user to re-run their original `/refact` command.
+
+`.refact-os.json` shape (`stack` is keyed by type; `ssh` is present only for SSH-push hosts like Kinsta/WP Engine and omitted for git-integration hosts like Vercel/Netlify):
+
+```json
+{
+  "stack": {
+    "wordpress": {
+      "hosting": "kinsta",
+      "runtime": "wp-env (PHP 8.2, MySQL 8)",
+      "environments": {
+        "production": { "url": "https://www.example.com/", "branch": "main", "ssh": { "user": "example", "host": "1.2.3.4", "port": 12345, "path": "/www/example_123/public" } },
+        "staging": { "url": "https://stg-example.kinsta.cloud/", "branch": "stage", "ssh": { "user": "example", "host": "1.2.3.4", "port": 54321, "path": "/www/example_123/public" } }
+      }
+    },
+    "nextjs": {
+      "hosting": "vercel",
+      "runtime": "Node 20 + pnpm",
+      "environments": {
+        "production": { "url": "https://app.example.com/", "branch": "main" },
+        "staging": { "url": "https://staging.example.com/", "branch": "develop" }
+      }
+    }
+  },
+  "asana": {
+    "projectId": "1209712345678901",
+    "projectUrl": "https://app.asana.com/0/1209712345678901"
+  }
+}
+```
+
+Secret credentials — `ASANA_TOKEN`, SSH **private keys**, deploy tokens — belong in `.env` or the CI secret store, never in `.refact-os.json`. The config holds only non-secret routing (hosts, ports, paths, branches, URLs).
+
+## Intent Routing
+
+This is an explicit command router: it maps a typed `/refact <action>` to the skill that does the work and **delegates** to it — it does not reimplement that skill's steps. Every target below carries its own `when_to_use`, so the agent can also select it directly without `/refact`; this table just makes the operations discoverable as typed commands.
+
+1. Parse the requested action from the user message.
+2. Route to the matching skill (load its `SKILL.md`):
+   - init / initialize / setup / bootstrap / "check what's left to configure" -> `agent/skills/setup-project/SKILL.md`
+   - package update / bump / reinstall requests -> `agent/skills/update-package/SKILL.md`
+   - chat history import requests -> `agent/skills/import-chat-history/SKILL.md`
+   - process docs / ingest docs / digest new inputs -> `agent/skills/process-docs/SKILL.md`
+   - status / what's pending / what's unprocessed -> `agent/skills/project-status/SKILL.md`
+   - git it / set up the repo / create the remote / first commit / publish to GitHub -> `agent/skills/git-it/SKILL.md`
+   - install wp skills / add WordPress skills / pull Gutenberg skills / vendor WP agent skills -> `agent/skills/install-wp-skills/SKILL.md` *(WordPress engagements only)*
+   - add codebase / clone repo into apps / scaffold app -> `agent/skills/add-codebase/SKILL.md` *(code overlay only)*
+   - sync asana / get asana tickets / pull asana / sync asana ticket <gid> -> `agent/skills/sync-asana/SKILL.md`
+   - setup kinsta auto-deploy / add kinsta deploy / enable kinsta auto-deploy / create kinsta workflows -> `agent/skills/setup-kinsta-deploy/SKILL.md` *(WordPress engagements only)*
+   - wp-env setup / start the local wp env / spin up wordpress locally / wp-env pull [plugins|mu-plugins|db] / mirror staging locally / wp-env reset / wp-env domain set <host> / wp-env domain clear / custom local domain / website.local instead of localhost -> `agent/skills/wp-env/SKILL.md` *(WordPress engagements only)*
+   - setup nextjs app / add Next.js app / create a Next.js app / adopt existing Next.js codebase -> `agent/skills/setup-nextjs-app/SKILL.md` *(Next.js engagements only)*
+   - nextjs dev / run the Next.js app / fix Next.js bug / update a Next.js route, component, server action, or API endpoint -> `agent/skills/nextjs-dev/SKILL.md` *(Next.js engagements only)*
+   - setup vercel deploy / deploy Next.js to Vercel / link this Next.js app to Vercel -> `agent/skills/setup-vercel-deploy/SKILL.md` *(Next.js + Vercel only)*
+   - setup netlify deploy / deploy Next.js to Netlify / link this Next.js app to Netlify -> `agent/skills/setup-netlify-deploy/SKILL.md` *(Next.js + Netlify only)*
+
+> The project-type skills ship only in their overlays. WordPress skills exist when `stack` has a `wordpress` entry; Next.js skills exist when `stack` has a `nextjs` entry. If the referenced skill folder is absent, tell the user to re-run `npx refact-os init --type <type>` or add the matching overlay.
+
+3. Load and follow the matched skill exactly, execute the needed commands, and report results. Each target is a standalone skill — the agent may also select it directly from its own `when_to_use` without going through `/refact`.
+
+## Examples
+
+- `/refact init`
+- `/refact initialize`
+- `/refact setup`
+- `/refact bootstrap`
+- `/refact update the package`
+- `/refact bump refact-os`
+- `/refact get chat history`
+- `/refact import chats`
+- `/refact process docs`
+- `/refact ingest new emails`
+- `/refact status`
+- `/refact what's unprocessed`
+- `/refact git it`
+- `/refact set up the repo`
+- `/refact create the remote`
+- `/refact publish to GitHub`
+- `/refact install wp skills`
+- `/refact add WordPress agent skills`
+- `/refact pull Gutenberg/block skills`
+- `/refact add codebase https://github.com/foo/bar`
+- `/refact add codebase wordpress`
+- `/refact add codebase seo`
+- `/refact sync asana`
+- `/refact get asana tickets`
+- `/refact sync asana ticket 1209712345678901`
+- `/refact setup kinsta auto-deploy`
+- `/refact add kinsta deploy`
+- `/refact create kinsta workflows`
+- `/refact wp-env setup`
+- `/refact wp-env pull`
+- `/refact wp-env pull plugins`
+- `/refact wp-env pull mu-plugins`
+- `/refact wp-env pull db`
+- `/refact wp-env reset`
+- `/refact wp-env domain set website.local`
+- `/refact wp-env domain clear`
+
+## If Unclear
+
+- Ask one focused clarifying question only when action cannot be inferred.
+- Otherwise proceed directly using the best matching reference.

package/templates/base/agent/skills/setup-project/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: setup-project
+description: Post-scaffold setup checklist — complete .refact-os.json (stack types, hosting, runtime, environments) and Asana, create .env, set up git/GitHub, and scaffold project-type slots.
+pattern: procedure
+when_to_use: /refact init | initialize | setup | bootstrap, or "check what's left to configure" after scaffolding.
+when_not_to_use: Routine code work (use code-development) or regenerating adapters (use refact-os sync).
+next_skills:
+  - git-it
+sub_agents: []
+---
+
+# Init Reference
+
+Use this reference when the user invokes any of:
+
+- `/refact init`
+- `/refact initialize`
+- `/refact setup`
+- `/refact bootstrap`
+
+## What this does
+
+Walks an **idempotent checklist** that brings a freshly-scaffolded project to a fully-configured state. Each checkbox is verified independently. If a checkbox is already met, skip it silently. If it isn't, handle that one item — by asking the user, editing files, or delegating to another reference — then re-verify and move on.
+
+The checklist is safe to re-run any time. Running `/refact init` on a fully-configured project should report "all checks pass" and do nothing.
+
+## Checklist
+
+Run each check in order. After handling any unmet item, re-check it before moving on.
+
+### 1. Project stack (`.refact-os.json` › `stack`)
+
+**Check:** `.refact-os.json` exists at the project root and `stack` names at least one project type. `stack` is an object **keyed by project type** — its keys *are* the type list. There is no separate `projectType`/`projectTypes`.
+
+| Field | Required | Value |
+|---|---|---|
+| `stack.<type>` | yes (≥1) | One key per type the repo is: `wordpress`, `nextjs`, and/or `blank` |
+| `asana.projectId` | optional | Numeric Asana project ID, or `null` to mark as not used |
+
+**Handle (if unmet):** Ask which project type(s) this engagement is (`wordpress`, `nextjs`, `blank`, or a hybrid like `wordpress,nextjs`). For each, ensure a `stack.<type>` entry exists with the shape `{ "hosting": null, "runtime": null, "environments": {} }` (detail is filled in step 2). For `asana.projectId`, accept `null` / "skip" / blank as an explicit opt-out — never leave the key absent. Prefer `npx refact-os init --type <type>` (or `--overlay <type>`) so the matching overlays get applied too.
+
+### 2. Stack details (`.refact-os.json` › `stack.<type>`)
+
+**Check:** Each `stack.<type>` entry has its `hosting`, `runtime`, and `environments` filled — or an explicit `null` / deliberate `{}` where not applicable. This is the **single home** for stack, hosting, and deploy facts; they are no longer duplicated in `agent/AGENTS.md`.
+
+**Per-type fields:**
+
+| Field | Example | Notes |
+|---|---|---|
+| `hosting` | `"kinsta"`, `"wpengine"`, `"vercel"`, `"netlify"` | Deploy provider for this type. |
+| `runtime` | `"wp-env (PHP 8.2, MySQL 8)"`, `"Node 20 + pnpm"` | Local dev / runtime stack. |
+| `environments.<env>` | keys like `production`, `staging` | One block per deployable environment; add others (e.g. `preview`) as needed. |
+
+**Per-environment fields** (`stack.<type>.environments.<env>`):
+
+| Field | Example | Notes |
+|---|---|---|
+| `url` | `"https://www.example.com/"` | Full URL including `https://`. |
+| `branch` | `"main"`, `"stage"`, `"develop"` | Git branch that auto-deploys to this environment. |
+| `ssh` | `{ "user": "example", "host": "1.2.3.4", "port": 12345, "path": "/www/<env>/public" }` | **SSH-push hosts only** (Kinsta, WP Engine). Omit entirely for git-integration hosts (Vercel, Netlify). Never store the private **key** here — that's a CI secret. |
+
+**Handle (if unmet):** Ask the user, one focused question at a time, for each type's `hosting` + `runtime` and at least its `production` (usually also `staging`) environment. Accept "skip" — leave the field `null` (or omit `ssh`) so it stays visibly outstanding without blocking init. Write directly into `.refact-os.json` and show the proposed change first. Collect **non-secret routing only** — SSH keys, tokens, and passwords belong in `.env` or the CI secret store, never here.
+
+### 3. `.env` file
+
+**Check:** `.env` exists at the project root. (`.env.example` is always shipped; we just want the local copy.)
+
+**Handle (if unmet):** Copy `.env.example` to `.env` (do not overwrite if `.env` already exists). Tell the user `.env` is gitignored and they should fill in any required tokens (e.g. `ASANA_TOKEN` if `.refact-os.json` › `asana.projectId` is set to a real ID).
+
+### 4. Git repository + GitHub remote
+
+**Check:**
+
+- `.git/` exists at the project root.
+- There is at least one commit (`git rev-parse --verify HEAD` succeeds).
+- A remote named `origin` exists and points at a GitHub URL (`git remote get-url origin` returns a github.com URL).
+
+**Handle (if unmet):** Delegate to `agent/skills/git-it/SKILL.md`. Run that flow exactly as documented there. Do not duplicate its prompts here — re-use the four questions (project name, slug, visibility, owner).
+
+### 5. WordPress app slot (WordPress projects only)
+
+**Skip this check** if `.refact-os.json` › `stack` has no `wordpress` entry.
+
+**Check:** `apps/wordpress/` exists and contains `wp-content/plugins/`, `wp-content/themes/`, and `wp-content/mu-plugins/`.
+
+**Handle (if unmet):** Delegate to `agent/skills/add-codebase/SKILL.md` with the argument `wordpress` (i.e. follow Flow B in that reference). After it runs, re-check the directory layout.
+
+### 6. WordPress agent skills (WordPress projects only)
+
+**Skip this check** if `.refact-os.json` › `stack` has no `wordpress` entry.
+
+**Check:** `.cursor/skills/wp-block-development/SKILL.md` exists. (Presence of this one is the cheap proxy for "the WP curated set has been installed at least once.")
+
+**Handle (if unmet):** Ask the user whether they want to install the curated WP skills now — it's optional and they may prefer to defer. If yes, delegate to `agent/skills/install-wp-skills/SKILL.md`. If no, mark the checkbox as user-deferred and move on; do not re-prompt on the next init run unless the user re-asks.
+
+### 7. Kinsta auto-deploy workflows (WordPress + Kinsta only)
+
+**Skip this check** if `.refact-os.json` › `stack` has no `wordpress` entry, **or** if `stack.wordpress.hosting` is not `kinsta`.
+
+**Check:** Both `.github/workflows/wordpress-deploy-stage.yml` and `.github/workflows/wordpress-deploy-main.yml` exist at the repo root.
+
+**Handle (if unmet):** Ask the user whether they want to create the Kinsta workflows now — it requires Kinsta-side SSH keys and GitHub Actions secrets, so they may want to defer. If yes, delegate to `agent/skills/setup-kinsta-deploy/SKILL.md`. If no, mark as user-deferred and move on.
+
+### 8. agent/AGENTS.md drift warning (post-update only)
+
+**Check:** The most recent scaffold run did **not** emit `⚠  agent/AGENTS.md template has changed upstream.`. (This warning is documented in `update-package.md` and stored hash-wise in `.refact-os.json` › `_scaffold.templateHashes`.)
+
+This check is informational — there's nothing to "fix". If the warning fired during a recent `/refact update the package` run and the user hasn't yet reviewed the diff, remind them: read `node_modules/refact-os/templates/AGENTS.md`, diff against the project's `agent/AGENTS.md`, and merge new sections by hand.
+
+## Output shape
+
+After running through the checklist, print a single summary:
+
+```
+init checklist:
+  [x] .refact-os.json stack + asana
+  [x] stack details (hosting/runtime/envs)
+  [x] .env file
+  [x] git + GitHub remote
+  [x] apps/wordpress/                (wordpress only)
+  [-] WordPress agent skills          (deferred by user)
+  [x] Kinsta auto-deploy workflows    (wordpress + kinsta only)
+  [x] agent/AGENTS.md drift                 (no pending warning)
+```
+
+Mark items as:
+- `[x]` met — handled successfully or already passing
+- `[-]` user-deferred — user declined to handle now
+- `[ ]` unmet and unresolved (only if the user aborted mid-step or a delegation failed)
+
+Surface unresolved items at the bottom with the suggested next action.
+
+## Guardrails
+
+- **Idempotent.** Re-running init on a fully-configured project must do nothing. Never re-prompt for a value that is already set.
+- **No silent edits.** Never write to `.refact-os.json` or `.env` without confirming with the user what is being set. Show the proposed change first.
+- **Delegate, don't duplicate.** For git, WP skills, WordPress scaffold, and Kinsta setup, follow the existing references step-for-step. Do not reimplement their logic here.
+- **Never** invent values for the user. If they don't know a value, accept "skip" and leave the field `null` (or omit an optional block like `ssh`) so it stays visibly outstanding.
+- **Never** edit `REFACT.md` from this flow — it's agency-wide and not project-specific.
+- If any single step fails, stop and report. Do not continue past a failed step — later checks may depend on it (e.g. `.env` before WP skills, git before any deploy setup).

package/templates/base/agent/skills/sync-asana/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: sync-asana
+description: Pull Asana tickets (open + completed) into docs/task/ as one markdown file per task.
+pattern: procedure
+when_to_use: /refact sync asana | get asana tickets | sync asana ticket <gid>.
+when_not_to_use: Opening a local ticket by hand (use open-ticket).
+next_skills: []
+sub_agents: []
+---
+
+# Asana Sync Reference
+
+Use this reference when the user invokes any of:
+
+- `/refact sync asana`
+- `/refact get asana tickets`
+- `/refact pull asana`
+- `/refact sync asana ticket <gid>`
+- `/refact get asana ticket <gid>`
+
+The implementation is **read-only**. It never writes back to Asana. Do not extend it to post comments or create tickets without an explicit owner approval and a follow-up PR.
+
+## What it does
+
+`.cursor/scripts/sync-asana.mjs` calls the Asana REST API and mirrors the configured project locally:
+
+- Walks every task in the Asana project (open **and** completed), paginated 100 at a time.
+- For each task, fetches details, subtasks, attachments, and the full story/comments thread.
+- Writes one markdown file per task into:
+  - `docs/task/open/<gid>.md` — open tasks
+  - `docs/task/closed/<gid>.md` — completed tasks
+- If a task transitions from open → completed (or back) since the previous sync, the file is moved between those directories automatically.
+- The script preserves the existing `processed: true|false` header value, so re-running does not undo work already done by `/refact process docs`.
+
+## Prerequisites
+
+| Requirement | Where it lives | Failure mode |
+|---|---|---|
+| Asana project ID | `.refact-os.json` → `asana.projectId` | Missing → the `preflight-metadata` hook blocks the prompt and asks for it (see `.cursor/skills/refact/SKILL.md` › Preflight). |
+| Asana personal access token | `.env` → `ASANA_TOKEN` | Missing → the script exits with: `ASANA_TOKEN is not set. Add it to .env`. Generate one at https://app.asana.com/0/my-apps. |
+
+If `asana.projectId` is `null` (the user explicitly skipped Asana during scaffolding), tell the user they need to set it to a real ID before this command can run, and offer to update `.refact-os.json` for them.
+
+## How to invoke
+
+Prefer the npm script wrappers — they keep the cwd correct and are the documented entry points:
+
+```bash
+npm run asana:sync               # full project sync
+npm run asana:sync:dry           # show what would change, write nothing
+npm run asana:sync -- --ticket 1209712345678901   # one task only
+```
+
+Direct invocation (equivalent):
+
+```bash
+node .cursor/scripts/sync-asana.mjs
+node .cursor/scripts/sync-asana.mjs --dry-run
+node .cursor/scripts/sync-asana.mjs --ticket 1209712345678901
+```
+
+The single-ticket path does not need `asana.projectId` — only the token — so it works for ad-hoc fetches even before a project is configured.
+
+## Workflow when the user invokes the skill
+
+1. **Parse intent.** Decide whether this is a full sync or a single-ticket sync. If the user named a ticket ID, use `--ticket <gid>`. Otherwise full sync.
+2. **Sanity check the prerequisites.** Read `.refact-os.json` and `.env` and confirm both `asana.projectId` (for full sync) and `ASANA_TOKEN` (always) are present. If either is missing, stop and tell the user what to do — do not run the script and hide the error.
+3. **Run the script** via the appropriate npm command above. Stream its output to the user.
+4. **Read the summary** the script prints on its last line, e.g. `Done. {"created":4,"updated":2,"moved":1,"unchanged":12}`.
+5. **Report** to the user:
+   - Total tasks synced (sum of all counters).
+   - Created / updated / moved / unchanged / error counts.
+   - If there were errors, list the failing task GIDs and what each error said.
+   - Remind them that newly-fetched tickets are still `processed: false`, so the next `/refact process docs` will integrate them into `docs/context/`.
+
+## Markdown layout produced
+
+```yaml
+---
+source: asana
+added-by: sync-asana.mjs
+processed: false
+asana-gid: 1209712345678901
+asana-permalink: https://app.asana.com/0/1209.../1209712345678901
+asana-modified-at: 2026-05-09T10:23:00.000Z
+asana-completed: false
+---
+```
+
+Followed by:
+
+- `# <task name>`
+- Single-line status header (status / assignee / due / start / section / tags / parent / completed-at).
+- `## Notes` (raw `task.notes` content).
+- `## Custom fields` if any have display values.
+- `## Subtasks (N)` — list with GIDs; subtasks are **not** synced as individual files in this version.
+- `## Attachments (N)` — links only, no downloads.
+- `## Comments / activity (N)` — every story (comments and system events).
+
+## Guardrails
+
+- **Never** edit a synced ticket file by hand expecting it to round-trip back to Asana. The script is one-way (Asana → local). Local edits are overwritten on the next sync.
+- **Never** flip `asana-completed:` manually to move a file between `asana/` and `asana/closed/`. The script does that based on Asana's truth.
+- **Never** commit `.env` or echo `ASANA_TOKEN` into chat / PR descriptions.
+- If a fetch fails with `401`, the token is invalid or revoked — tell the user to regenerate it. If it fails with `403`, the token is valid but does not have access to that project.
+- If the project has thousands of tasks, the first sync may take a couple of minutes. Don't add a flag to "skip closed tickets" — completed history is the whole reason to mirror locally.

package/templates/base/agent/skills/update-canonical-record/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: update-canonical-record
+description: Make a surgical, cited edit to the project's canonical truth file (blueprint/proposal/spec/charter/brief) when synthesized knowledge changes.
+pattern: procedure
+when_to_use: New synthesized truth needs to be reflected in the canonical record — a confirmed decision, a scope change, a resolved open question.
+when_not_to_use: For raw inbound material (use ingest-input) or volatile in-progress state (use docs/task/). Don't edit the canonical record from unverified evidence.
+inputs:
+  - the canonical record file named in docs/index.md
+  - supporting evidence under docs/sources/ and entries in docs/decisions.md
+outputs:
+  - a surgical edit to the canonical record, with a citation to the source
+next_skills: []
+sub_agents: []
+---
+
+# Update Canonical Record
+
+## Steps
+
+1. Read `docs/index.md` to find which file is the canonical record (it varies by project: `blueprint.md`, `proposal.md`, `spec.md`, `charter.md`, `brief.md`).
+2. Make the smallest edit that captures the new truth. Cite the source (evidence path, decision date, ticket).
+3. If the change conflicts with existing canonical text, record the contradiction rather than silently overwriting — note both and flag for a human.
+4. If this finalizes a decision, also append to `docs/decisions.md`.
+
+## Hard rules
+
+- Knowledge wins over evidence on conflict, but only *after* synthesis — don't promote an unverified source claim straight into the canonical record.
+- Surgical edits only. Don't rewrite whole sections to make one change.

package/templates/base/agent/skills/update-package/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: update-package
+description: Update/bump/reinstall the refact-os package from GitHub, refresh the agent payload (prune removed skills, regenerate adapters), and report what changed.
+pattern: procedure
+when_to_use: /refact update the package | bump refact-os | reinstall | "get the latest refact-os" | "are we on the latest standard".
+when_not_to_use: Installing WordPress agent skills (use install-wp-skills). Bringing a drifted repo fully in line (after updating, use adopt).
+next_skills: []
+sub_agents: []
+---
+
+# Update Package Reference
+
+Use this when the user asks to update / bump / refresh / reinstall `refact-os` in the current repo. Goal: pull the latest package, let it refresh the agent payload, and report what changed — including anything that needs a manual merge.
+
+## Source
+
+`refact-os` installs from GitHub (`github:refactco/refact-os`) — it is **not** on the public npm registry, so `npm install refact-os@latest` will fail. Use the GitHub specifier unless the user explicitly names a local checkout (e.g. `../refact-os` for development).
+
+## Workflow
+
+1. **Detect the package manager** from lockfiles: `pnpm-lock.yaml` → pnpm; `yarn.lock` → yarn; `package-lock.json` or none → npm.
+2. **Bump the package** (show the command first; let the user override the source):
+   - npm: `npm install github:refactco/refact-os`
+   - pnpm: `pnpm add github:refactco/refact-os`
+   - yarn: `yarn add github:refactco/refact-os`
+
+   Installing as a devDependency does **not** auto-scaffold (postinstall skips when refact-os is a project dependency), so apply the refresh explicitly in the next step.
+3. **Refresh the payload:** `npx refact-os init` (or `npm run refact:update`). It is idempotent and:
+   - force-copies package-managed files (the `agent/` skills, hooks, scripts, root pointers); your own files are preserved (`agent/AGENTS.md`, `README.md`, everything under `docs/`).
+   - **prunes** skills the package removed or renamed since your last update (tracked via `_scaffold.shippedSkills` in `.refact-os.json`); skills you authored are never pruned.
+   - regenerates `.cursor/` and `.claude/` from `agent/`.
+   - prints the version transition (`old → new`) and any pruned skills.
+4. **Read the output** and surface to the user:
+   - the version transition — point them at `node_modules/refact-os/CHANGELOG.md` for what changed and whether anything needs manual action.
+   - any pruned skills.
+   - the **`agent/AGENTS.md` drift warning** if it fired (the upstream contract template changed; your copy is never overwritten).
+5. **agent/AGENTS.md drift follow-up** (only if the warning fired): read the installed template at `node_modules/refact-os/templates/base/agent/AGENTS.md` and the project's `agent/AGENTS.md`, diff them, and surface the meaningful additions as *suggestions*. Wait for the user's go-ahead before editing; preserve project-specific values (stack, hosting, URLs, SSH) — never replace them with template placeholders.
+6. **Validate:** run `npm run refact:validate` and report the result. If it surfaces structural gaps (common when the standard adds folders/roles), suggest `/adopt` to reconcile them.
+7. **Report:** source used, installed version/SHA, version transition, files changed, pruned skills, whether the AGENTS.md drift fired, and follow-up steps (review the diff, run tests, commit).
+
+## Local checkout (opt-in only)
+
+If the user explicitly wants to install from a local clone (developing refact-os itself), use the path they name (e.g. `npm install ../refact-os`). Don't assume that layout exists.
+
+## Guardrails
+
+- Prefer package-manager commands over hand-editing `package.json`.
+- Never reach for the npm registry as a fallback — the package isn't published there.
+- Never run destructive git commands.
+- If install fails, capture the exact error and suggest the smallest fix — don't silently retry with a different source.
+- The refresh prunes only skills the package previously shipped. If the user customized a package skill in place (discouraged — fork it with a project prefix instead), warn them it will be overwritten or pruned.

package/templates/base/docs/context/project.md

@@ -0,0 +1,30 @@
+---
+date: <TODO: yyyy-mm-dd>
+status: active
+description: Stable engagement context — who the client is, what we're building, and the working agreements that don't change week to week.
+---
+
+# Project Context
+
+> Stable engagement context. Volatile state lives in `docs/task/`; this file changes rarely.
+
+## What this engagement is
+
+<TODO: one paragraph — client name, scope, why this engagement exists.>
+
+> Stack, hosting, and per-environment deploy config live in `.refact-os.json` (keyed by project type), not here.
+
+## Working agreements
+
+- Decisions are traceable: anything decided on the client's behalf is recorded in `docs/decisions.md` with the data it was based on.
+- Open questions have an owner: pending calls live in `docs/context/open-decisions.md`, each tagged with a responsible person.
+- Evidence is captured before it's used: emails, transcripts, and tickets land in `docs/sources/raw/` first — agents work from those files, not from chat memory.
+- Secrets are local-only: per-user tokens live in `.env`, never committed.
+
+## Source precedence (what wins on conflict)
+
+1. Explicit current user instruction.
+2. The canonical record (see `docs/index.md`).
+3. Latest `docs/decisions.md` entry.
+4. Latest call transcript / client artifact.
+5. Older references.

package/templates/base/docs/decisions.md

@@ -0,0 +1,22 @@
+# Decisions
+
+Finalized decisions — what was decided, why, and the data the decision was based on. Agents append here whenever they (or a human) make a non-trivial decision on the project.
+
+Each entry **must** include the supporting data, so that weeks later we can answer "why did this happen?" without digging through chat logs.
+
+> When this file gets unwieldy to scan, split it by **date range** (e.g. `docs/decisions/2026-Q1.md`), not by topic — chronology is unambiguous, topic classification isn't. Until then, one file greps fine.
+
+## Entry format
+
+```
+## YYYY-MM-DD — One-line summary
+
+- **Decision:** what was decided.
+- **Why:** the reason. Link the request / ticket / email if there is one.
+- **Data:** the inputs this decision was based on (IDs, file paths under docs/, ticket numbers, email subjects).
+- **Owner:** who decided. If an agent decided autonomously, say "agent (autonomous)". If a human approved, add "approved by: <name>".
+```
+
+## Entries
+
+<!-- newest first -->

package/templates/base/docs/index.md

@@ -0,0 +1,31 @@
+# docs/ — project index
+
+Lazy catalog of this engagement's substrate. Agents read this first to know where to look. Update it when a new top-level doc earns its place.
+
+## Canonical record
+
+This project's canonical truth lives in `<TODO: blueprint.md | proposal.md | spec.md | charter.md | brief.md>`. Until that file is created, the canonical record is this index plus the most recent `decisions.md` entries. `/refact init` will help name and create it.
+
+## Where things live (the seven roles)
+
+| Role | Path | What's there |
+|---|---|---|
+| **Evidence** | `docs/sources/raw/` | Inbound material as received — `email/`, `call-transcripts/`, `agent-transcripts/`. Never edited. |
+| **Knowledge** | `docs/context/`, `docs/decisions.md` | Curated truth: `project.md`, `people.md`, `open-decisions.md`, `learnings.md`, plus the decision log. `context/company/` (when synced) holds Refact-wide brand/team context from `refact-operation`. |
+| **Task** | `docs/task/` | In-progress work: tickets in `open/`, completed under `closed/`. |
+| **Output** | `docs/deliverables/` | Reviewed, ready-to-share artifacts only. |
+| **Software** | `apps/`, `packages/` | Runnable code (created when the engagement has code). |
+| **Agent** | `agent/` | Shared contract, skills, hooks, scripts. Canonical; `.cursor/` and `.claude/` are generated from it. |
+
+## Read order for a new agent
+
+1. `agent/AGENTS.md` — the contract: stack, hard rules, growth triggers.
+2. This index.
+3. The canonical record (once named).
+4. Recent `decisions.md` entries.
+
+## Update rules
+
+- New top-level doc → add a row above.
+- Evidence is read-only. Knowledge wins on conflict with evidence.
+- Folders mark information *role*; status/owner/type are frontmatter, not folders.

package/templates/base/env.example

@@ -0,0 +1,14 @@
+# Per-user secrets. Copy this file to .env and fill in your own values.
+# .env is gitignored — never commit it.
+
+# Cursor API key — required for the extract-learnings hook (.cursor/hooks/extract-learnings.mjs).
+# Get one from Cursor Dashboard → Integrations.
+CURSOR_API_KEY=
+
+# Owner name written into chat transcript meta files. Falls back to git user.name if unset.
+CURSOR_CHAT_OWNER=
+
+# Asana Personal Access Token — used when the agent ingests tickets via Asana's API.
+# Generate one at: https://app.asana.com/0/my-apps → Personal Access Tokens.
+# The non-secret Asana *project ID* lives in .refact-os.json, not here.
+ASANA_TOKEN=

package/templates/base/gitignore

@@ -0,0 +1,34 @@
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Build output / caches
+**/build/
+**/dist/
+**/.cache/
+**/.next/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Agent tool personal overrides — the shared .claude/settings.json is committed
+# (team-wide, generated by refact-os); per-user tweaks go here and stay local.
+.claude/settings.local.json
+
+# Secrets — keep .env.example
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# Database dumps
+*.sql
+*.sql.gz

package/templates/overlays/client/agent/skills/create-deliverable/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: create-deliverable
+description: Promote a reviewed internal draft to docs/deliverables/ (information role Task -> Output), flipping status to sent and logging the event.
+pattern: procedure
+requires_approval: true
+when_to_use: A draft in docs/internal/ has been reviewed and approved and is ready to leave the building.
+when_not_to_use: For drafts still in progress (keep them in docs/internal/ with status frontmatter), or for raw evidence.
+inputs:
+  - an approved draft in docs/internal/<type>/<slug>.md
+outputs:
+  - docs/deliverables/<type>/<slug>.md with status sent
+next_skills: []
+sub_agents: []
+---
+
+# Create Deliverable
+
+## Steps
+
+1. Confirm the draft is approved (ask once if unclear).
+2. Move it from `docs/internal/<type>/<slug>.md` to `docs/deliverables/<type>/<slug>.md` (create the destination folder on the fly). This is a *role change*, Task → Output, so it earns a file move.
+3. Set frontmatter `status: sent` (or `signed` for contracts).
+4. Log the event in `docs/decisions.md` or the linked ticket.
+5. Report the deliverable path.
+
+## Hard rules
+
+- Only reviewed, ready-to-share artifacts land in `docs/deliverables/`. Drafts stay in `docs/internal/`.
+- Sensitive outputs (signed contracts, NDAs) may need `.gitignore` rules — flag, don't auto-commit.