@refactco/refact-os 1.5.0

package/templates/base/agent/skills/git-it/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: git-it
+description: Initialize the git repo, make the first commit, and create the GitHub remote.
+pattern: procedure
+requires_approval: true
+when_to_use: /refact git it | set up the repo | create the remote | first commit | publish to GitHub.
+when_not_to_use: Feature work on an existing repo (use code-development).
+next_skills: []
+sub_agents: []
+---
+
+# Git It Reference
+
+Use this reference when the user invokes `/refact git it` (or asks to "set up the repo", "create the remote", "make the first commit", "publish to GitHub").
+
+## Goal
+
+Get this project from "no git history" to "pushed to a fresh GitHub repo" with one guided flow:
+1. Make sure `gh` is installed and authenticated.
+2. Ask the user 4 short questions.
+3. `git init` if needed, make the first commit if there isn't one, `gh repo create`, push.
+
+## Step 1 — Prerequisites
+
+### 1a. Check for the GitHub CLI
+
+```bash
+command -v gh
+```
+
+If it's missing, **detect the OS** and **show the right install command**, then **ask the user for permission** before running it. Never run install commands autonomously (especially anything with `sudo`).
+
+| OS | Suggested install |
+|---|---|
+| macOS (Homebrew) | `brew install gh` |
+| Debian / Ubuntu | follow https://cli.github.com/manual/installation (uses an apt repository, requires sudo) |
+| Fedora / RHEL | `sudo dnf install gh` |
+| Arch | `sudo pacman -S github-cli` |
+| Windows (winget) | `winget install --id GitHub.cli` |
+
+Detect OS with `uname -s` (Darwin / Linux) and, on Linux, `cat /etc/os-release` for the distro.
+
+If the user declines or you can't auto-install, stop here and ask them to install `gh` and re-run `/refact git it`.
+
+### 1b. Check authentication
+
+```bash
+gh auth status
+```
+
+If it reports "not logged in" or fails: stop and tell the user to run `gh auth login` themselves — it's an interactive OAuth flow you can't drive for them. Once they confirm they've logged in, continue.
+
+## Step 2 — Ask the user 4 questions
+
+Ask one at a time; accept the suggested default if the user just confirms.
+
+### Q1: Project name
+
+- **Default suggestion:** humanize the current directory name. e.g. `flower-shop` → "Flower Shop".
+- Use this for the eventual repo description and the README's H1 if it still has `<TODO: project name>`.
+
+### Q2: Slug (repo name on GitHub)
+
+- **Default suggestion:** lowercase the project name, replace any non-alphanumeric run with a single `-`, strip leading/trailing `-`.
+- The slug must be valid for GitHub (`^[a-zA-Z0-9._-]+$`). If it isn't, suggest a corrected one and re-ask.
+
+### Q3: Visibility
+
+- **Default: `private`.**
+- Other valid choice: `public`.
+- Don't offer `internal` unless the user specifically asks for it.
+
+### Q4: Owner
+
+Run:
+
+```bash
+gh api user/orgs --jq '.[].login'
+```
+
+- If the list is empty → owner is the authenticated user. Get it with `gh api user --jq '.login'`. No question needed; just confirm.
+- If the list has one or more orgs → present `<user>, <org1>, <org2>, …` and ask which one. Default to the personal account.
+
+## Step 3 — Execute
+
+Run the steps below in order. Stop on the first error and surface it; do not retry destructively.
+
+### 3a. Initialize git if needed
+
+```bash
+test -d .git || git init -b main
+```
+
+If `.git` already exists, leave the current branch alone.
+
+### 3b. Ensure a first commit exists
+
+Check:
+
+```bash
+git rev-parse --verify HEAD 2>/dev/null
+```
+
+If that fails (no commits yet):
+
+```bash
+git add -A
+git commit -m "chore: initial commit (refact-os scaffold)"
+```
+
+If commits already exist, **do not** create a synthetic "initial" commit on top — just continue.
+
+### 3c. Create the remote and push
+
+```bash
+gh repo create <owner>/<slug> --<visibility> --source=. --remote=origin --push --description "<humanized project name>"
+```
+
+- `<visibility>` is literally `--private` or `--public`.
+- If a remote named `origin` already exists locally, do **not** overwrite it. Stop and ask the user.
+- If `gh` reports the slug is taken on the chosen owner, surface the exact error and ask for a different slug. Do not invent a fallback name yourself.
+
+### 3d. Report
+
+Print:
+
+- Remote URL: `gh repo view --json url --jq .url`
+- First commit hash + subject: `git log -1 --format='%h %s'`
+- Two suggested next steps: "invite collaborators with `gh repo edit --add-collaborator …`" and "set branch protection in the GitHub UI".
+
+## Guardrails
+
+- **Never** run `sudo` autonomously. Always ask permission first.
+- **Never** force-push. If `git push` fails, stop and surface the error.
+- **Never** overwrite an existing `origin` remote.
+- **Never** commit `.env`, `*.pem`, `*.key`, or anything matched by `.gitignore`. The generated `.gitignore` covers these, but verify by inspecting `git status` before the first commit.
+- **Never** invent the slug or organization on the user's behalf — always show the suggestion and let them confirm or override.
+- If the working tree has nothing to commit AND no prior commits exist, stop and ask the user to add something first — `gh repo create --source=.` requires a non-empty initial commit.

package/templates/base/agent/skills/import-chat-history/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: import-chat-history
+description: Import the project's Claude Code / Cursor chat history into docs/sources/raw/agent-transcripts/.
+pattern: procedure
+when_to_use: /refact get chat history | import chats.
+when_not_to_use: Saving brand-new inbound material (use ingest-input) — this is only for agent chat logs.
+next_skills:
+  - process-docs
+sub_agents: []
+---
+
+# Chat History Reference
+
+Backfill this project's agent chats into:
+
+- `docs/sources/raw/agent-transcripts/`
+
+Use this reference when handling requests such as `/refact get chat history` or `/refact import chats`.
+
+> New **Claude Code** chats are mirrored here automatically by the
+> `claude-sync-transcript` hook (on every Stop). This script is for backfilling
+> history that predates the hook, and for importing **Cursor** chats. It is
+> local-only — nothing is sent to the remote server.
+
+## Script
+
+- `.claude/scripts/import-project-chat-history.py` (or `.cursor/scripts/…` — identical copies)
+
+## Default behavior
+
+With `--tool auto` (the default) the script imports from whichever sources exist
+for this repo, auto-detecting both:
+
+- Claude Code: `~/.claude/projects/<encoded-cwd>/*.jsonl` (full native transcripts;
+  `<encoded-cwd>` is the absolute repo path with `/` and `.` replaced by `-`)
+- Cursor: `~/.cursor/projects/<project-key>/agent-transcripts/*.jsonl`
+
+## Usage
+
+From project root:
+
+```bash
+npm run chats:import
+# or:
+python3 .claude/scripts/import-project-chat-history.py
+```
+
+Restrict to one tool:
+
+```bash
+python3 .claude/scripts/import-project-chat-history.py --tool claude
+python3 .claude/scripts/import-project-chat-history.py --tool cursor
+```
+
+Dry run:
+
+```bash
+npm run chats:import:dry
+# or:
+python3 .claude/scripts/import-project-chat-history.py --dry-run
+```
+
+Custom source (overrides auto-detection):
+
+```bash
+python3 .claude/scripts/import-project-chat-history.py --source "/absolute/path/to/transcripts"
+```
+
+Custom owner for generated meta files:
+
+```bash
+python3 .claude/scripts/import-project-chat-history.py --owner "Owner Name"
+```
+
+## Optional environment variables
+
+- `CLAUDE_PROJECT_TRANSCRIPTS_DIR`: override the Claude Code source directory.
+- `CURSOR_PROJECT_TRANSCRIPTS_DIR`: override the Cursor source directory.
+- `REFACT_CHAT_OWNER` / `CURSOR_CHAT_OWNER`: default owner for generated `.meta.json` files.
+
+## What it imports
+
+- Copies all `*.jsonl` chat transcript files from the detected source(s) to the destination.
+- Updates files only when content changed (SHA-256 compare).
+- Creates `<chat-id>.meta.json` when missing (includes `session_id`, `owner`, `tool`, and source info).

package/templates/base/agent/skills/ingest-input/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ingest-input
+description: Classify and save any inbound material (email, transcript, deck, file, RFP, chat) into docs/sources/raw/ with a dated filename and a small frontmatter header, then suggest the next move.
+pattern: procedure
+when_to_use: The user pastes or points at new inbound material — "here's an email from the client", "save this transcript", "a new RFP came in", "add this file".
+when_not_to_use: For material that already lives in docs/sources/raw/ (just read it), or when the user wants curated truth updated (use update-canonical-record), or to open a ticket (use open-ticket).
+inputs:
+  - the pasted or referenced inbound material
+outputs:
+  - a dated file under docs/sources/raw/<class>/ with a 3-line header
+next_skills:
+  - open-ticket            # if the material implies trackable work
+  - update-canonical-record # if it changes curated truth
+sub_agents: []
+---
+
+# Ingest Input
+
+The universal entry point for any material arriving from outside the codebase. Capture it as Evidence *before* acting on it — agents work from saved files, not chat memory.
+
+## Steps
+
+1. **Classify the input type** and pick the destination + extension:
+   - email → `docs/sources/raw/email/<yyyy-mm-dd>-<slug>.email.md`
+   - meeting/call transcript → `docs/sources/raw/call-transcripts/<yyyy-mm-dd>-<slug>.transcript.md`
+   - agent chat history → `docs/sources/raw/agent-transcripts/` (usually synced by the hook; only save by hand if pasted)
+   - document / deck / RFP / misc file → `docs/sources/raw/<yyyy-mm-dd>-<slug>.<type>.md`
+2. **Write the file** with a 3-line header:
+   ```yaml
+   ---
+   source: gmail | fathom | asana | other
+   added-by: <name or "agent">
+   processed: false
+   ---
+   ```
+3. **Never edit** raw evidence after saving — it is received state.
+4. **Detect the pattern** in the content (quote request, scope change, bug report, decision) and surface the relevant `next_skills` to the user.
+
+## Hard rules
+
+- Raw is evidence: write once, never rewrite.
+- One file per item. Date-prefix the filename.
+- Bucket by source class only when volume earns it; flat files under `raw/` are fine for light projects.

package/templates/base/agent/skills/open-ticket/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: open-ticket
+description: Create a tracked ticket under docs/task/open/ with frontmatter, linking the source evidence that prompted it.
+pattern: procedure
+when_to_use: A piece of work needs tracking — a client request, a bug, a scoped task — and there isn't already an open ticket for it.
+when_not_to_use: For closing a ticket (use close-ticket), or for work small enough to finish in the same turn without tracking.
+inputs:
+  - the source evidence file under docs/sources/raw/ (if any)
+outputs:
+  - docs/task/open/<yyyy-mm-dd>-<slug>.md with status frontmatter
+next_skills: []
+sub_agents: []
+---
+
+# Open Ticket
+
+## Steps
+
+1. Create `docs/task/open/<yyyy-mm-dd>-<slug>.md`.
+2. Add frontmatter:
+   ```yaml
+   ---
+   date: <yyyy-mm-dd>
+   status: open
+   description: <one line: what needs doing and why>
+   source: <path to docs/sources/raw/... if this came from inbound material>
+   ---
+   ```
+3. Write a short body: the ask, acceptance criteria, and any links.
+4. Tell the user the ticket path.
+
+## Notes
+
+- One markdown file per ticket. `docs/task/open/` holds active tickets.
+- Status transitions (`open → in-progress`) are frontmatter, not folder moves.
+- When the ticket closes, hand off to `close-ticket`.

package/templates/base/agent/skills/process-docs/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: process-docs
+description: Walk unprocessed files under docs/sources/raw/, integrate them into docs/context/, and flip the processed flag.
+pattern: procedure
+when_to_use: /refact process docs | ingest new emails | digest new inputs.
+when_not_to_use: Saving material that hasn't been captured yet (use ingest-input first).
+next_skills: []
+sub_agents: []
+---
+
+# Process Docs Reference
+
+Use this reference when the user invokes `/refact process-docs` (or asks to process / ingest / digest new docs).
+
+## What "processing" means
+
+Every file under `docs/` (except `agent-transcripts/`, which is for raw chat history) has a 3-line YAML header with a `processed` flag. "Processing" means reading an unprocessed file, integrating its information into `docs/context/`, and flipping the flag.
+
+## Workflow
+
+### 1. Find unprocessed files
+
+Don't hand-walk folders to find them — "which files are unprocessed" is a deterministic question, so let a script answer it (a model eyeballing folders is right most times and silently off once). Run the shared scanner (the same one `project-status` uses) and read its `unprocessed.files` list:
+
+```bash
+node agent/skills/project-status/scripts/scan-status.mjs --json
+```
+
+Every path in `unprocessed.files` is a `.md` file with `processed: false` somewhere under `docs/` (raw chat logs in `agent-transcripts/` are already excluded). That list is your work queue for the steps below — the *judgment* about what each file means is yours; the *enumeration* is not.
+
+### 2. For each unprocessed file, decide what to update
+
+Read the file. Then update one or more of these, as appropriate:
+
+- **`docs/decisions.md`** — if the file records a finalized decision. Include the source file path under `docs/` as part of the **Data** field of the entry.
+- **`docs/context/open-decisions.md`** — if the file raises a question, ambiguity, or request that needs a human's call. Tag the responsible person from `docs/context/people.md`. If the right person isn't in roles, ask the user.
+- **`docs/context/people.md`** — if the file mentions a new person on either team. Append a bullet with name + role.
+- **`docs/context/learnings.md`** — if the file contains a non-obvious project/customer preference or convention worth remembering.
+
+A single file can update multiple `docs/context/` files. Some files may update none — if the content is purely informational and not actionable, no `docs/context/` change is needed, but you still flip the header (see step 3).
+
+### 3. Flip the header
+
+After processing, change the file's header from `processed: false` to `processed: true`. Leave `source` and `added-by` untouched.
+
+### 4. Report
+
+Print a concise summary at the end:
+
+```
+Processed N files.
+
+decisions.md: +X entries
+open-decisions.md: +Y entries
+people.md: +Z entries
+learnings.md: +W bullets
+
+Files processed:
+- docs/sources/raw/email/2026-05-09-customer-feedback.md
+- docs/sources/raw/call-transcripts/2026-05-10-weekly-sync.md
+- ...
+```
+
+## Guardrails
+
+- **Never** add an entry to `decisions.md` without including the source `docs/` file path as part of the **Data** field. Traceability is the whole point of that file.
+- **Never** invent a person for `people.md`. If a name appears in a doc but the role is unclear, surface it as an open question instead.
+- **Never** flip `processed: true` if you skipped the file due to an error — leave the flag as-is so it gets retried next time.
+- If a file's content seems duplicated against an existing `docs/context/` entry, prefer **updating** the existing entry over adding a new one.

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

@@ -0,0 +1,35 @@
+---
+name: project-status
+description: Report what's unprocessed, open decisions and their owners, recent learnings, and unfilled placeholders.
+pattern: procedure
+when_to_use: /refact status | what's pending | what's unprocessed.
+when_not_to_use: Making a change — this is read-only reporting.
+next_skills: []
+sub_agents: []
+---
+
+# Status Reference
+
+Use this when the user invokes `/refact status` (or asks "what's the status of the project context?").
+
+## How it works
+
+The scan — counting unprocessed files, open decisions, and role placeholders, and pulling recent learnings — is **deterministic work, so a script does it**, not the model. Eyeballing folders and counting by hand is exactly the kind of mechanical task a model gets *plausibly* wrong (right most times, silently off once). Run:
+
+```bash
+node agent/skills/project-status/scripts/scan-status.mjs
+```
+
+It prints a ready-to-show snapshot: unprocessed docs (grouped by folder), open decisions, recent learnings, and unfilled role placeholders. Add `--json` if you want to post-process the facts instead of showing them.
+
+## What you do
+
+1. Run the script from the repo root.
+2. Present its output as the snapshot — it's already under ~20 lines and human-readable.
+3. **Then** add the one thing the script can't: judgment. If something stands out — a pile of unprocessed inbound, a decision that's been open a long time, roles still unfilled — say so in a line and suggest the next move (`/refact process docs`, or resolving a specific decision). That interpretation is the only part of this skill that belongs to you.
+
+## Scope
+
+- This reports project **context** state, not repo health. Adapter drift, missing skill frontmatter, and structure checks are `refact-os validate`'s job — don't duplicate them here.
+- Read-only. Don't modify any files.
+- If the script reports a file as "not present," relay that — it's normal early in a project, since those `docs/context/` files are earned, not seeded.

package/templates/base/agent/skills/project-status/scripts/scan-status.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// Deterministic status scan for the project-status skill (`/refact status`).
+//
+// Counts unprocessed docs, open decisions, and role placeholders, and lists the
+// most recent learnings — the mechanical facts the model must NOT eyeball-count
+// (see the standard's "Latent vs. Deterministic Work"). The skill body runs this
+// and adds interpretation on top; it does not re-derive these numbers by hand.
+//
+//   node agent/skills/project-status/scripts/scan-status.mjs          # text snapshot
+//   node agent/skills/project-status/scripts/scan-status.mjs --json   # machine-readable
+//
+// Paths resolve relative to this file, so it works whether it's run from the
+// canonical agent/ copy or a generated .cursor/ / .claude/ mirror. Repo-structure
+// health (adapter drift, skill frontmatter) is `refact-os validate`'s job, not
+// this script's — this reports project *context* state only.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(scriptDir, "../../../..");
+const docs = path.join(root, "docs");
+const asJson = process.argv.includes("--json");
+
+function read(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function walk(dir, acc = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === "agent-transcripts") continue; // raw chat logs — never "processed"
+      walk(full, acc);
+    } else if (e.name.endsWith(".md")) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+// 1. Unprocessed docs: files whose frontmatter carries `processed: false`.
+// `byFolder` powers the snapshot count; `files` is the exact list process-docs
+// consumes so it never has to hand-walk folders either.
+const unprocessed = {};
+const unprocessedFiles = [];
+for (const file of walk(docs)) {
+  const head = (read(file) || "").slice(0, 800);
+  if (/^processed:\s*false\s*$/m.test(head)) {
+    const label = path.basename(path.dirname(file));
+    unprocessed[label] = (unprocessed[label] || 0) + 1;
+    unprocessedFiles.push(path.relative(root, file));
+  }
+}
+const unprocessedTotal = unprocessedFiles.length;
+
+// 2. Open decisions: dated bullet entries in docs/context/open-decisions.md.
+const openDecRaw = read(path.join(docs, "context", "open-decisions.md"));
+const openDecisions = [];
+if (openDecRaw != null) {
+  for (const line of openDecRaw.split("\n")) {
+    const m = line.match(/^-\s+(\d{4}-\d{2}-\d{2}\b.*)$/);
+    if (m) openDecisions.push(m[1].trim());
+  }
+}
+
+// 3. Recent learnings: newest 3 bullets under "## Entries" (newest-first by convention).
+const learnRaw = read(path.join(docs, "context", "learnings.md"));
+const learnings = [];
+if (learnRaw != null) {
+  const idx = learnRaw.indexOf("## Entries");
+  const body = idx >= 0 ? learnRaw.slice(idx) : learnRaw;
+  for (const line of body.split("\n")) {
+    const m = line.match(/^-\s+(.+)$/);
+    if (m) {
+      learnings.push(m[1].trim());
+      if (learnings.length >= 3) break;
+    }
+  }
+}
+
+// 4. Role placeholders: unfilled <TODO> markers in docs/context/people.md.
+const peopleRaw = read(path.join(docs, "context", "people.md"));
+const rolePlaceholders = peopleRaw == null ? null : (peopleRaw.match(/<TODO>/g) || []).length;
+
+const missing = [
+  openDecRaw == null && "docs/context/open-decisions.md",
+  learnRaw == null && "docs/context/learnings.md",
+  peopleRaw == null && "docs/context/people.md",
+].filter(Boolean);
+
+if (asJson) {
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        unprocessed: { total: unprocessedTotal, byFolder: unprocessed, files: unprocessedFiles },
+        openDecisions: openDecRaw == null ? null : openDecisions,
+        recentLearnings: learnRaw == null ? null : learnings,
+        rolePlaceholders,
+        missing,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+} else {
+  const lines = [];
+  if (unprocessedTotal === 0) {
+    lines.push("Unprocessed: all docs processed.");
+  } else {
+    const parts = Object.entries(unprocessed).map(([k, v]) => `${v} ${k}`);
+    lines.push(`Unprocessed: ${parts.join(", ")} (${unprocessedTotal} total).`);
+  }
+
+  if (openDecRaw == null) {
+    lines.push("Open decisions: (docs/context/open-decisions.md not present).");
+  } else if (openDecisions.length === 0) {
+    lines.push("Open decisions: none.");
+  } else {
+    lines.push(`Open decisions: ${openDecisions.length}.`);
+    for (const d of openDecisions) lines.push(`  - ${d}`);
+  }
+
+  if (learnRaw == null) {
+    lines.push("Recent learnings: (docs/context/learnings.md not present).");
+  } else if (learnings.length === 0) {
+    lines.push("Recent learnings: none yet.");
+  } else {
+    lines.push("Recent learnings:");
+    for (const l of learnings) lines.push(`  - ${l}`);
+  }
+
+  if (peopleRaw == null) {
+    lines.push("Roles: (docs/context/people.md not present).");
+  } else if (rolePlaceholders > 0) {
+    lines.push(`Roles: ${rolePlaceholders} <TODO> placeholder(s) in people.md.`);
+  } else {
+    lines.push("Roles: all filled.");
+  }
+
+  process.stdout.write(`${lines.join("\n")}\n`);
+}