gentle-pi 0.1.0

package/extensions/skill-registry.ts

@@ -0,0 +1,267 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, relative } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const REGISTRY_REL_PATH = ".atl/skill-registry.md";
+const CACHE_REL_PATH = ".atl/.skill-registry.cache.json";
+const SECTION_MARKER = "## Selected skills and compact rules";
+const EXCLUDE_NAMES = new Set(["_shared", "skill-registry"]);
+const EXCLUDE_PREFIXES = ["sdd-"];
+
+interface SkillEntry {
+	name: string;
+	path: string;
+	description: string;
+	rules: string[];
+}
+
+function userSkillDirs(): string[] {
+	const home = homedir();
+	return [
+		join(home, ".pi/agent/skills"),
+		join(home, ".agents/skills"),
+		join(home, ".config/opencode/skills"),
+		join(home, ".claude/skills"),
+		join(home, ".gemini/skills"),
+		join(home, ".cursor/skills"),
+		join(home, ".copilot/skills"),
+	];
+}
+
+function projectSkillDirs(cwd: string): string[] {
+	return [
+		join(cwd, ".pi/skills"),
+		join(cwd, ".agents/skills"),
+		join(cwd, ".claude/skills"),
+		join(cwd, ".atl/skills"),
+	];
+}
+
+function findSkillFiles(root: string): string[] {
+	if (!existsSync(root)) return [];
+	const out: string[] = [];
+	const stack: string[] = [root];
+	while (stack.length > 0) {
+		const dir = stack.pop()!;
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				stack.push(full);
+			} else if (entry.isFile() && entry.name === "SKILL.md") {
+				out.push(full);
+			}
+		}
+	}
+	return out;
+}
+
+function parseFrontmatter(source: string): { name?: string; description?: string; body: string } {
+	if (!source.startsWith("---\n")) return { body: source };
+	const end = source.indexOf("\n---", 4);
+	if (end === -1) return { body: source };
+	const fm = source.slice(4, end);
+	const body = source.slice(end + 4).replace(/^\n/, "");
+	const out: { name?: string; description?: string } = {};
+	for (const line of fm.split("\n")) {
+		const m = line.match(/^(\w+):\s*(.*)$/);
+		if (!m) continue;
+		const key = m[1];
+		let value = m[2].trim();
+		if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+			value = value.slice(1, -1);
+		}
+		if (key === "name") out.name = value;
+		else if (key === "description") out.description = value;
+	}
+	return { ...out, body };
+}
+
+function extractCompactRulesSection(body: string): string[] {
+	const lines = body.split("\n");
+	let inSection = false;
+	const rules: string[] = [];
+	for (const raw of lines) {
+		const line = raw.trimEnd();
+		if (/^##\s+Compact Rules\s*$/i.test(line)) {
+			inSection = true;
+			continue;
+		}
+		if (!inSection) continue;
+		if (/^##\s+/.test(line)) break;
+		const m = line.match(/^-\s+(.+)$/);
+		if (m) rules.push(m[1].trim());
+	}
+	return rules;
+}
+
+function deriveSkillName(file: string, frontmatterName: string | undefined): string {
+	if (frontmatterName) return frontmatterName;
+	return basename(join(file, ".."));
+}
+
+function isExcluded(name: string): boolean {
+	if (EXCLUDE_NAMES.has(name)) return true;
+	return EXCLUDE_PREFIXES.some((p) => name.startsWith(p));
+}
+
+function loadSkill(file: string): SkillEntry | undefined {
+	let source: string;
+	try {
+		source = readFileSync(file, "utf8");
+	} catch {
+		return undefined;
+	}
+	const fm = parseFrontmatter(source);
+	const name = deriveSkillName(file, fm.name);
+	if (isExcluded(name)) return undefined;
+	const rules = extractCompactRulesSection(fm.body);
+	if (rules.length === 0) return undefined;
+	return {
+		name,
+		path: file,
+		description: fm.description ?? "",
+		rules,
+	};
+}
+
+function dedupeBySkillName(entries: SkillEntry[], cwd: string): SkillEntry[] {
+	const projectPrefix = cwd.endsWith("/") ? cwd : `${cwd}/`;
+	const buckets = new Map<string, SkillEntry[]>();
+	for (const entry of entries) {
+		const list = buckets.get(entry.name) ?? [];
+		list.push(entry);
+		buckets.set(entry.name, list);
+	}
+	const out: SkillEntry[] = [];
+	for (const [, list] of buckets) {
+		const projectScoped = list.find((e) => e.path.startsWith(projectPrefix));
+		out.push(projectScoped ?? list[0]);
+	}
+	return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function fingerprint(files: string[]): string {
+	const lines = files
+		.map((f) => {
+			try {
+				const stat = statSync(f);
+				return `${f}:${stat.mtimeMs}:${stat.size}`;
+			} catch {
+				return `${f}:missing`;
+			}
+		})
+		.sort();
+	return createHash("sha1").update(lines.join("\n")).digest("hex");
+}
+
+function renderRegistry(cwd: string, sources: string[], entries: SkillEntry[]): string {
+	const projectName = basename(cwd);
+	const today = new Date().toISOString().slice(0, 10);
+	const lines: string[] = [];
+	lines.push(`# Skill Registry — ${projectName}`);
+	lines.push("");
+	lines.push("<!-- Auto-generated by .pi/extensions/skill-registry.ts. Run /skill-registry:refresh to regenerate. -->");
+	lines.push("");
+	lines.push(`Last updated: ${today}`);
+	lines.push("");
+	lines.push("## Sources scanned");
+	lines.push("");
+	for (const src of sources) {
+		lines.push(`- ${src}`);
+	}
+	lines.push("");
+	lines.push(SECTION_MARKER);
+	lines.push("");
+	for (const entry of entries) {
+		lines.push(`### ${entry.name}`);
+		lines.push(`- Path: ${entry.path}`);
+		if (entry.description) {
+			lines.push(`- Trigger: ${entry.description}`);
+		}
+		lines.push("- Rules:");
+		for (const rule of entry.rules) {
+			lines.push(`  - ${rule}`);
+		}
+		lines.push("");
+	}
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+
+interface RegenResult {
+	regenerated: boolean;
+	skillCount: number;
+	reason: string;
+}
+
+function regenerateRegistry(cwd: string, force: boolean): RegenResult {
+	const dirs = [...userSkillDirs(), ...projectSkillDirs(cwd)];
+	const existingDirs = dirs.filter((d) => existsSync(d));
+	const files = existingDirs.flatMap(findSkillFiles).sort();
+	const cachePath = join(cwd, CACHE_REL_PATH);
+	const registryPath = join(cwd, REGISTRY_REL_PATH);
+	const fp = fingerprint(files);
+	let cached: string | undefined;
+	if (existsSync(cachePath)) {
+		try {
+			cached = (JSON.parse(readFileSync(cachePath, "utf8")) as { fingerprint?: string }).fingerprint;
+		} catch {
+			cached = undefined;
+		}
+	}
+	if (!force && cached === fp && existsSync(registryPath)) {
+		return { regenerated: false, skillCount: 0, reason: "cache-hit" };
+	}
+	const entries = files
+		.map(loadSkill)
+		.filter((e): e is SkillEntry => Boolean(e));
+	const deduped = dedupeBySkillName(entries, cwd);
+	const sources = existingDirs.map((d) => {
+		const rel = relative(cwd, d);
+		return rel.startsWith("..") ? d : rel || ".";
+	});
+	const md = renderRegistry(cwd, sources, deduped);
+	mkdirSync(join(cwd, ".atl"), { recursive: true });
+	writeFileSync(registryPath, md);
+	writeFileSync(cachePath, JSON.stringify({ fingerprint: fp }, null, 2));
+	return { regenerated: true, skillCount: deduped.length, reason: force ? "forced" : "fingerprint-changed" };
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		try {
+			const result = regenerateRegistry(ctx.cwd, false);
+			if (result.regenerated && ctx.hasUI) {
+				ctx.ui.notify(`Skill registry refreshed (${result.skillCount} skills)`, "info");
+			}
+		} catch (error) {
+			if (ctx.hasUI) {
+				const message = error instanceof Error ? error.message : String(error);
+				ctx.ui.notify(`Skill registry refresh failed: ${message}`, "warning");
+			}
+		}
+	});
+
+	pi.registerCommand("skill-registry:refresh", {
+		description: "Regenerate .atl/skill-registry.md from local skill sources.",
+		handler: async (_args, ctx) => {
+			try {
+				const result = regenerateRegistry(ctx.cwd, true);
+				ctx.ui.notify(
+					`Skill registry: ${result.skillCount} skill(s) written to ${REGISTRY_REL_PATH}`,
+					"info",
+				);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				ctx.ui.notify(`Skill registry refresh failed: ${message}`, "warning");
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "gentle-pi",
+  "version": "0.1.0",
+  "description": "Opinionated Gentle Pi harness package: SDD/OpenSpec workflow, strict TDD guidance, subagent assets, and safety defaults.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "gentle-pi",
+    "sdd",
+    "openspec",
+    "subagents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gentleman-Programming/gentle-pi.git",
+    "directory": "pi-packages/gentle-ai"
+  },
+  "files": [
+    "assets/",
+    "extensions/",
+    "prompts/",
+    "skills/",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  }
+}

package/prompts/cl.md

@@ -0,0 +1,54 @@
+---
+description: Audit changelog entries before release
+---
+Audit changelog entries for all commits since the last release.
+
+## Process
+
+1. **Find the last release tag:**
+   ```bash
+   git tag --sort=-version:refname | head -1
+   ```
+
+2. **List all commits since that tag:**
+   ```bash
+   git log <tag>..HEAD --oneline
+   ```
+
+3. **Read each package's [Unreleased] section:**
+   - packages/ai/CHANGELOG.md
+   - packages/tui/CHANGELOG.md
+   - packages/coding-agent/CHANGELOG.md
+
+4. **For each commit, check:**
+   - Skip: changelog updates, doc-only changes, release housekeeping
+   - Skip: changes to generated model catalogs (for example `packages/ai/src/models.generated.ts`) unless accompanied by an intentional product-facing change in non-generated source/docs.
+   - Determine which package(s) the commit affects (use `git show <hash> --stat`)
+   - Verify a changelog entry exists in the affected package(s)
+   - For external contributions (PRs), verify format: `Description ([#N](url) by [@user](url))`
+
+5. **Cross-package duplication rule:**
+   Changes in `ai`, `agent` or `tui` that affect end users should be duplicated to `coding-agent` changelog, since coding-agent is the user-facing package that depends on them.
+
+6. **Add New Features section after changelog fixes:**
+   - Insert a `### New Features` section at the start of `## [Unreleased]` in `packages/coding-agent/CHANGELOG.md`.
+   - Propose the top new features to the user for confirmation before writing them.
+   - Link to relevant docs and sections whenever possible.
+
+7. **Report:**
+   - List commits with missing entries
+   - List entries that need cross-package duplication
+   - Add any missing entries directly
+
+## Changelog Format Reference
+
+Sections (in order):
+- `### Breaking Changes` - API changes requiring migration
+- `### Added` - New features
+- `### Changed` - Changes to existing functionality
+- `### Fixed` - Bug fixes
+- `### Removed` - Removed features
+
+Attribution:
+- Internal: `Fixed foo ([#123](https://github.com/earendil-works/pi-mono/issues/123))`
+- External: `Added bar ([#456](https://github.com/earendil-works/pi-mono/pull/456) by [@user](https://github.com/user))`

package/prompts/is.md

@@ -0,0 +1,25 @@
+---
+description: Analyze GitHub issues (bugs or feature requests)
+argument-hint: "<issue>"
+---
+Analyze GitHub issue(s): $ARGUMENTS
+
+For each issue:
+
+1. Add the `inprogress` label to the issue via GitHub CLI before analysis starts. If adding the label fails, report that explicitly and continue.
+2. Read the issue in full, including all comments and linked issues/PRs.
+3. Do not trust analysis written in the issue. Independently verify behavior and derive your own analysis from the code and execution path.
+
+4. **For bugs**:
+   - Ignore any root cause analysis in the issue (likely wrong)
+   - Read all related code files in full (no truncation)
+   - Trace the code path and identify the actual root cause
+   - Propose a fix
+
+5. **For feature requests**:
+   - Do not trust implementation proposals in the issue without verification
+   - Read all related code files in full (no truncation)
+   - Propose the most concise implementation approach
+   - List affected files and changes needed
+
+Do NOT implement unless explicitly asked. Analyze and propose only.

package/prompts/pr.md

@@ -0,0 +1,41 @@
+---
+description: Review PRs from URLs with structured issue and code analysis
+argument-hint: "<PR-URL>"
+---
+You are given one or more GitHub PR URLs: $@
+
+For each PR URL, do the following in order:
+1. Add the `inprogress` label to the PR via GitHub CLI before analysis starts. If adding the label fails, report that explicitly and continue.
+2. Read the PR page in full. Include description, all comments, all commits, and all changed files.
+3. Identify any linked issues referenced in the PR body, comments, commit messages, or cross links. Read each issue in full, including all comments.
+4. Analyze the PR diff. Read all relevant code files in full with no truncation from the current main branch and compare against the diff. Do not fetch PR file blobs unless a file is missing on main or the diff context is insufficient. Include related code paths that are not in the diff but are required to validate behavior.
+5. Check for a changelog entry in the relevant `packages/*/CHANGELOG.md` files. Report whether an entry exists. If missing, state that a changelog entry is required before merge and that you will add it if the user decides to merge. Follow the changelog format rules in AGENTS.md. Verify:
+   - Entry uses correct section (`### Breaking Changes`, `### Added`, `### Fixed`, etc.)
+   - External contributions include PR link and author: `Fixed foo ([#123](https://github.com/earendil-works/pi-mono/pull/123) by [@user](https://github.com/user))`
+   - Breaking changes are in `### Breaking Changes`, not just `### Fixed`
+6. Check if packages/coding-agent/README.md, packages/coding-agent/docs/*.md, packages/coding-agent/examples/**/*.md require modification. This is usually the case when existing features have been changed, or new features have been added.
+7. Provide a structured review with these sections:
+   - Good: solid choices or improvements
+   - Bad: concrete issues, regressions, missing tests, or risks
+   - Ugly: subtle or high impact problems
+8. Add Questions or Assumptions if anything is unclear.
+9. Add Change summary and Tests.
+
+Output format per PR:
+PR: <url>
+Changelog:
+- ...
+Good:
+- ...
+Bad:
+- ...
+Ugly:
+- ...
+Questions or Assumptions:
+- ...
+Change summary:
+- ...
+Tests:
+- ...
+
+If no issues are found, say so under Bad and Ugly.

package/prompts/wr.md

@@ -0,0 +1,31 @@
+---
+description: Finish the current task end-to-end with changelog, commit, and push
+argument-hint: "[instructions]"
+---
+Wrap it.
+
+Additional instructions: $ARGUMENTS
+
+Determine context from the conversation history first.
+
+Rules for context detection:
+- If the conversation already mentions a GitHub issue or PR, use that existing context.
+- If the work came from `/is` or `/pr`, assume the issue or PR context is already known from the conversation and from the analysis work already done.
+- If there is no GitHub issue or PR in the conversation history, treat this as non-GitHub work.
+
+Unless I explicitly override something in this request, do the following in order:
+
+1. Add or update the relevant package changelog entry under `## [Unreleased]` using the repo changelog rules.
+2. If this task is tied to a GitHub issue or PR and a final issue or PR comment has not already been posted in this session, draft it in my tone, preview it, and post exactly one final comment.
+3. Commit only files you changed in this session.
+4. If this task is tied to exactly one GitHub issue, include `closes #<issue>` in the commit message. If it is tied to multiple issues, stop and ask which one to use. If it is not tied to any issue, do not include `closes #` or `fixes #` in the commit message.
+5. Check the current git branch. If it is not `main`, stop and ask what to do. Do not push from another branch unless I explicitly say so.
+6. Push the current branch.
+
+Constraints:
+- Never stage unrelated files.
+- Never use `git add .` or `git add -A`.
+- Run required checks before committing if code changed.
+- Do not open a PR unless I explicitly ask.
+- If this is not GitHub issue or PR work, do not post a GitHub comment.
+- If a final issue or PR comment was already posted in this session, do not post another one unless I explicitly ask.

package/skills/branch-pr/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: branch-pr
+description: "Create Gentle AI pull requests with issue-first checks. Trigger: creating, opening, or preparing PRs for review."
+license: Apache-2.0
+metadata:
+  author: gentleman-programming
+  version: "2.0"
+---
+
+## When to Use
+
+Use this skill when:
+- Creating a pull request for any change
+- Preparing a branch for submission
+- Helping a contributor open a PR
+
+---
+
+## Critical Rules
+
+1. **Every PR MUST link an approved issue** — no exceptions
+2. **Every PR MUST have exactly one `type:*` label**
+3. **Automated checks must pass** before merge is possible
+4. **Blank PRs without issue linkage will be blocked** by GitHub Actions
+
+---
+
+## Workflow
+
+```
+1. Verify issue has `status:approved` label
+2. Create branch: type/description (see Branch Naming below)
+3. Implement changes with conventional commits
+4. Run shellcheck on modified scripts
+5. Open PR using the template
+6. Add exactly one type:* label
+7. Wait for automated checks to pass
+```
+
+---
+
+## Branch Naming
+
+Branch names MUST match this regex:
+
+```
+^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
+```
+
+**Format:** `type/description` — lowercase, no spaces, only `a-z0-9._-` in description.
+
+| Type | Branch pattern | Example |
+|------|---------------|---------|
+| Feature | `feat/<description>` | `feat/user-login` |
+| Bug fix | `fix/<description>` | `fix/zsh-glob-error` |
+| Chore | `chore/<description>` | `chore/update-ci-actions` |
+| Docs | `docs/<description>` | `docs/installation-guide` |
+| Style | `style/<description>` | `style/format-scripts` |
+| Refactor | `refactor/<description>` | `refactor/extract-shared-logic` |
+| Performance | `perf/<description>` | `perf/reduce-startup-time` |
+| Test | `test/<description>` | `test/add-setup-coverage` |
+| Build | `build/<description>` | `build/update-shellcheck` |
+| CI | `ci/<description>` | `ci/add-branch-validation` |
+| Revert | `revert/<description>` | `revert/broken-setup-change` |
+
+---
+
+## PR Body Format
+
+The PR template is at `.github/PULL_REQUEST_TEMPLATE.md`. Every PR body MUST contain:
+
+### 1. Linked Issue (REQUIRED)
+
+```markdown
+Closes #<issue-number>
+```
+
+Valid keywords: `Closes #N`, `Fixes #N`, `Resolves #N` (case insensitive).
+The linked issue MUST have the `status:approved` label.
+
+### 2. PR Type (REQUIRED)
+
+Check exactly ONE in the template and add the matching label:
+
+| Checkbox | Label to add |
+|----------|-------------|
+| Bug fix | `type:bug` |
+| New feature | `type:feature` |
+| Documentation only | `type:docs` |
+| Code refactoring | `type:refactor` |
+| Maintenance/tooling | `type:chore` |
+| Breaking change | `type:breaking-change` |
+
+### 3. Summary
+
+1-3 bullet points of what the PR does.
+
+### 4. Changes Table
+
+```markdown
+| File | Change |
+|------|--------|
+| `path/to/file` | What changed |
+```
+
+### 5. Test Plan
+
+```markdown
+- [x] Scripts run without errors: `shellcheck scripts/*.sh`
+- [x] Manually tested the affected functionality
+- [x] Skills load correctly in target agent
+```
+
+### 6. Contributor Checklist
+
+All boxes must be checked:
+- Linked an approved issue
+- Added exactly one `type:*` label
+- Ran shellcheck on modified scripts
+- Skills tested in at least one agent
+- Docs updated if behavior changed
+- Conventional commit format
+- No `Co-Authored-By` trailers
+
+---
+
+## Automated Checks (all must pass)
+
+| Check | Job name | What it verifies |
+|-------|----------|-----------------|
+| PR Validation | `Check Issue Reference` | Body contains `Closes/Fixes/Resolves #N` |
+| PR Validation | `Check Issue Has status:approved` | Linked issue has `status:approved` |
+| PR Validation | `Check PR Has type:* Label` | PR has exactly one `type:*` label |
+| CI | `Shellcheck` | Shell scripts pass `shellcheck` |
+
+---
+
+## Conventional Commits
+
+Commit messages MUST match this regex:
+
+```
+^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
+```
+
+**Format:** `type(scope): description` or `type: description`
+
+- `type` — required, one of: `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`
+- `(scope)` — optional, lowercase with `a-z0-9._-`
+- `!` — optional, indicates breaking change
+- `description` — required, starts after `: `
+
+Type-to-label mapping:
+
+| Commit type | PR label |
+|-------------|----------|
+| `feat` | `type:feature` |
+| `fix` | `type:bug` |
+| `docs` | `type:docs` |
+| `refactor` | `type:refactor` |
+| `chore` | `type:chore` |
+| `style` | `type:chore` |
+| `perf` | `type:feature` |
+| `test` | `type:chore` |
+| `build` | `type:chore` |
+| `ci` | `type:chore` |
+| `revert` | `type:bug` |
+| `feat!` / `fix!` | `type:breaking-change` |
+
+Examples:
+```
+feat(scripts): add Codex support to setup.sh
+fix(skills): correct topic key format in sdd-apply
+docs(readme): update multi-model configuration guide
+refactor(skills): extract shared persistence logic
+chore(ci): add shellcheck to PR validation workflow
+perf(scripts): reduce setup.sh execution time
+style(skills): fix markdown formatting
+test(scripts): add setup.sh integration tests
+ci(workflows): add branch name validation
+revert: undo broken setup change
+feat!: redesign skill loading system
+```
+
+---
+
+## Commands
+
+```bash
+# Create branch
+git checkout -b feat/my-feature main
+
+# Run shellcheck before pushing
+shellcheck scripts/*.sh
+
+# Push and create PR
+git push -u origin feat/my-feature
+gh pr create --title "feat(scope): description" --body "Closes #N"
+
+# Add type label to PR
+gh pr edit <pr-number> --add-label "type:feature"
+```