@chankov/agent-skills 0.1.0

package/docs/gemini-cli-setup.md

@@ -0,0 +1,113 @@
+# Using agent-skills with Gemini CLI
+
+## Setup
+
+### Option 1: Install as Skills (Recommended)
+
+Gemini CLI has a native skills system that auto-discovers `SKILL.md` files in `.gemini/skills/` or `.agents/skills/` directories. Each skill activates on demand when it matches your task.
+
+**Install from the repo:**
+
+```bash
+gemini skills install https://github.com/chankov/agent-skills.git --path skills
+```
+
+**Or install from a local clone:**
+
+```bash
+git clone https://github.com/chankov/agent-skills.git
+gemini skills install /path/to/agent-skills/skills/
+```
+
+**Install for a specific workspace only:**
+
+```bash
+gemini skills install /path/to/agent-skills/skills/ --scope workspace
+```
+
+Skills installed at workspace scope go into `.gemini/skills/` (or `.agents/skills/`). User-level skills go into `~/.gemini/skills/`.
+
+Once installed, verify with:
+
+```
+/skills list
+```
+
+Gemini CLI injects skill names and descriptions into the prompt automatically. When it recognizes a matching task, it asks permission to activate the skill before loading its full instructions.
+
+### Option 2: GEMINI.md (Persistent Context)
+
+For skills you want always loaded as persistent project context (rather than on-demand activation), add them to your project's `GEMINI.md`:
+
+```bash
+# Create GEMINI.md with core skills as persistent context
+cat /path/to/agent-skills/skills/incremental-implementation/SKILL.md > GEMINI.md
+echo -e "\n---\n" >> GEMINI.md
+cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> GEMINI.md
+```
+
+You can also modularize by importing from separate files:
+
+```markdown
+# Project Instructions
+
+@skills/test-driven-development/SKILL.md
+@skills/incremental-implementation/SKILL.md
+```
+
+Use `/memory show` to verify loaded context, and `/memory reload` to refresh after changes.
+
+> **Skills vs GEMINI.md:** Skills are on-demand expertise that activate only when relevant, keeping your context window clean. GEMINI.md provides persistent context loaded for every prompt. Use skills for phase-specific workflows and GEMINI.md for always-on project conventions.
+
+## Recommended Configuration
+
+### Always-On (GEMINI.md)
+
+Add these as persistent context for every session:
+
+- `incremental-implementation` — Build in small verifiable slices
+- `code-review-and-quality` — Five-axis review
+
+### On-Demand (Skills)
+
+Install these as skills so they activate only when relevant:
+
+- `test-driven-development` — Activates when implementing logic or fixing bugs
+- `spec-driven-development` — Activates when starting a new project or feature
+- `frontend-ui-engineering` — Activates when building UI
+- `security-and-hardening` — Activates during security reviews
+- `performance-optimization` — Activates during performance work
+
+## Advanced Configuration
+
+### MCP Integration
+
+Many skills in this pack leverage [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools to interact with the environment. For example:
+
+- `browser-testing-with-devtools` uses the `chrome-devtools` MCP extension.
+- `performance-optimization` can benefit from performance-related MCP tools.
+
+To enable these, ensure you have the relevant MCP extensions installed in your Gemini CLI configuration (`~/.gemini/config.json`).
+
+### Session Hooks
+
+Gemini CLI supports session lifecycle hooks. You can use these to automatically inject context or run validation scripts at the start of a session.
+
+To replicate the `agent-skills` experience from other tools, you can configure a `SessionStart` hook that reminds you of the available skills or loads a meta-skill.
+
+### Explicit Context Loading
+
+You can explicitly load any skill into your current session by referencing it with the `@` symbol in your prompt:
+
+```markdown
+Use the @skills/test-driven-development/SKILL.md skill to implement this fix.
+```
+
+This is useful when you want to ensure a specific workflow is followed without waiting for auto-discovery.
+
+## Usage Tips
+
+1. **Prefer skills over GEMINI.md** — Skills activate on demand and keep your context window focused. Only put skills in GEMINI.md if you want them always loaded.
+2. **Skill descriptions matter** — Each SKILL.md has a `description` field in its frontmatter that tells agents when to activate it. The descriptions in this repo are optimized for auto-discovery across all supported tools (Claude Code, Gemini CLI, etc.) by clearly stating both *what* the skill does and *when* it should be triggered.
+3. **Use agents for review** — Copy `agents/code-reviewer.md` content when requesting structured code reviews. The full persona set lives in `agents/`: `code-reviewer`, `test-engineer`, `security-auditor`, `planner`, `plan-reviewer`, `builder`, `scout`, `documenter`. Read-only personas (`code-reviewer`, `security-auditor`, `planner`, `plan-reviewer`, `scout`) declare `tools: read,bash,grep,find,ls` and refuse to write.
+4. **Combine with references** — Reference checklists from `references/` when working on specific quality areas like testing or performance.

package/docs/getting-started.md

@@ -0,0 +1,162 @@
+# Getting Started with agent-skills
+
+agent-skills works with any AI coding agent that accepts Markdown instructions. This guide covers the universal approach. For tool-specific setup, see the dedicated guides.
+
+## How Skills Work
+
+Each skill is a Markdown file (`SKILL.md`) that describes a specific engineering workflow. When loaded into an agent's context, the agent follows the workflow — including verification steps, anti-patterns to avoid, and exit criteria.
+
+**Skills are not reference docs.** They're step-by-step processes the agent follows.
+
+## Install path — which one fits you?
+
+| Audience | Path | Why |
+|---|---|---|
+| **Most users** — you want to use the skills in your projects | `npx @chankov/agent-skills init` | One command; semver updates; cross-platform; no source dir to babysit. See [docs/npm-install.md](npm-install.md). |
+| **Claude Code users** — you live in Claude Code and want plugin-managed updates | `/plugin marketplace add chankov/agent-skills` | Best UX inside Claude Code; marketplace handles the lifecycle. |
+| **Skill authors / contributors** — you want to edit the skills and have changes flow into every connected workspace | `git clone` + `symlink` mode in `/setup` | Edit-in-place; every connected workspace sees the change instantly. |
+
+All three converge on the same `guided-workspace-setup` skill — they only differ in how the source files reach your workspace. None is being deprecated.
+
+## Quick Start (Any Agent)
+
+### 1. Clone the repository
+
+```bash
+git clone https://github.com/chankov/agent-skills.git
+```
+
+> Skip this step if you installed via npm — the package contents are already
+> in `node_modules/agent-skills/`. Use that path wherever this guide refers to
+> "the agent-skills repo."
+
+### 2. Choose a skill
+
+Browse the `skills/` directory. Each subdirectory contains a `SKILL.md` with:
+- **When to use** — triggers that indicate this skill applies
+- **Process** — step-by-step workflow
+- **Verification** — how to confirm the work is done
+- **Common rationalizations** — excuses the agent might use to skip steps
+- **Red flags** — signs the skill is being violated
+
+### 3. Load the skill into your agent
+
+Copy the relevant `SKILL.md` content into your agent's system prompt, rules file, or conversation. The most common approaches:
+
+**System prompt:** Paste the skill content at the start of the session.
+
+**Rules file:** Add skill content to your project's rules file (CLAUDE.md, .cursorrules, etc.).
+
+**Conversation:** Reference the skill when giving instructions: "Follow the test-driven-development process for this change."
+
+### 4. Use the meta-skill for discovery
+
+Start with the `using-agent-skills` skill loaded. It contains a flowchart that maps task types to the appropriate skill.
+
+## Recommended Setup
+
+### Minimal (Start here)
+
+Load three essential skills into your rules file:
+
+1. **spec-driven-development** — For defining what to build
+2. **test-driven-development** — For proving it works
+3. **code-review-and-quality** — For verifying quality before merge
+
+These three cover the most critical quality gaps in AI-assisted development.
+
+### Full Lifecycle
+
+For comprehensive coverage, load skills by phase:
+
+```
+Starting a project:  spec-driven-development → planning-and-task-breakdown
+During development:  incremental-implementation + test-driven-development
+Before merge:        code-review-and-quality + security-and-hardening
+Before deploy:       shipping-and-launch
+```
+
+### Context-Aware Loading
+
+Don't load all skills at once — it wastes context. Load skills relevant to the current task:
+
+- Working on UI? Load `frontend-ui-engineering`
+- Debugging? Load `debugging-and-error-recovery`
+- Setting up CI? Load `ci-cd-and-automation`
+
+## Skill Anatomy
+
+Every skill follows the same structure:
+
+```
+YAML frontmatter (name, description)
+├── Overview — What this skill does
+├── When to Use — Triggers and conditions
+├── Core Process — Step-by-step workflow
+├── Examples — Code samples and patterns
+├── Common Rationalizations — Excuses and rebuttals
+├── Red Flags — Signs the skill is being violated
+└── Verification — Exit criteria checklist
+```
+
+See [skill-anatomy.md](skill-anatomy.md) for the full specification.
+
+## Using Agents
+
+The `agents/` directory contains pre-configured agent personas:
+
+| Agent | Purpose |
+|-------|---------|
+| `code-reviewer.md` | Five-axis code review (read-only) |
+| `test-engineer.md` | Test strategy and writing |
+| `security-auditor.md` | Vulnerability detection (read-only) |
+| `planner.md` | Numbered implementation plans (read-only) |
+| `plan-reviewer.md` | Critiques and validates plans (read-only) |
+| `builder.md` | Implements an approved plan |
+| `scout.md` | Fast codebase recon (read-only) |
+| `documenter.md` | READMEs and inline docs |
+
+Load an agent definition when you need specialized review. For example, ask your coding agent to "review this change using the code-reviewer agent persona" and provide the agent definition.
+
+## Using Commands
+
+The `.claude/commands/` directory contains slash commands for Claude Code:
+
+| Command | Skill Invoked |
+|---------|---------------|
+| `/setup` | guided-workspace-setup |
+| `/spec` | spec-driven-development |
+| `/plan` | planning-and-task-breakdown |
+| `/build` | incremental-implementation + test-driven-development |
+| `/test` | test-driven-development |
+| `/review` | code-review-and-quality |
+| `/ship` | shipping-and-launch |
+
+## Using References
+
+The `references/` directory contains supplementary checklists:
+
+| Reference | Use With |
+|-----------|----------|
+| `testing-patterns.md` | test-driven-development |
+| `performance-checklist.md` | performance-optimization |
+| `security-checklist.md` | security-and-hardening |
+| `accessibility-checklist.md` | frontend-ui-engineering |
+
+Load a reference when you need detailed patterns beyond what the skill covers.
+
+## Spec and task artifacts
+
+The `/spec` and `/plan` commands create working artifacts (`SPEC.md`, `tasks/plan.md`, `tasks/todo.md`). Treat them as **living documents** while the work is in progress:
+
+- Keep them in version control during development so the human and the agent have a shared source of truth.
+- Update them when scope or decisions change.
+- If your repo doesn’t want these files long‑term, delete them before merge or add the folder to `.gitignore` — the workflow doesn’t require them to be permanent.
+
+## Tips
+
+1. **Start with spec-driven-development** for any non-trivial work
+2. **Always load test-driven-development** when writing code
+3. **Don't skip verification steps** — they're the whole point
+4. **Load skills selectively** — more context isn't always better
+5. **Use the agents for review** — different perspectives catch different issues

package/docs/npm-install.md

@@ -0,0 +1,169 @@
+# npm install path
+
+The `@chankov/agent-skills` package ships every skill, persona, slash command,
+and pi extension as installable content, plus a thin CLI that hands off to the
+LLM-driven `guided-workspace-setup` skill. The CLI never writes installable
+artifacts on its own — that decision (and the conversation around it) belongs
+to the coding agent.
+
+## Package name vs CLI name
+
+| | Name |
+|---|---|
+| **npm package** (use this for `npm install` and the first `npx`) | `@chankov/agent-skills` |
+| **CLI binary** (the command the package ships) | `agent-skills` |
+
+The package is published under the `@chankov` npm scope to guarantee identity —
+only [Nikolay Chankov](https://www.npmjs.com/~chankov) can publish to that
+scope. The CLI binary stays the short name `agent-skills` because that's what
+goes on `PATH` after install.
+
+So:
+
+- First time / one-shot: `npx @chankov/agent-skills <cmd>` — npx resolves the
+  scoped package and runs its bin.
+- After a project / global install: `npx agent-skills <cmd>` works too,
+  because the bin is named `agent-skills`.
+
+## Quick start
+
+```bash
+# In the workspace you want to configure:
+npx @chankov/agent-skills init
+# Then open your coding agent in this directory and run:
+#   /setup
+```
+
+That's it. `npx` fetches the package, the CLI detects your coding agent and
+prints the next-step command, and `/setup` runs the full guided install
+inside your agent.
+
+## Commands
+
+### `npx @chankov/agent-skills init`
+
+Materializes the package and hands off to `/setup`.
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--agent <claude-code\|opencode\|pi>` | auto-detect | Skip the agent prompt |
+| `--method <copy\|symlink>` | `copy` | Default install method passed to the skill |
+| `--workspace <path>` | `cwd` | Target workspace |
+| `--launch` | off | Shell into the coding agent after init (best effort) |
+
+```bash
+npx @chankov/agent-skills init --agent claude-code
+npx @chankov/agent-skills init --workspace ~/projects/foo --method symlink
+```
+
+### `npx @chankov/agent-skills doctor`
+
+Deterministic preflight scan — walks every install-target directory, lists
+broken symlinks and stale persona references, and offers fixes. Same scan
+that `/doctor` runs inside the agent.
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--workspace <path>` | `cwd` | Target workspace |
+| `--dry-run` | off | Show findings; do not apply |
+| `--yes` / `-y` | off | Apply all suggested fixes without prompting |
+
+```bash
+npx @chankov/agent-skills doctor --workspace ~/projects/foo --dry-run
+npx @chankov/agent-skills doctor -y
+```
+
+### `npx @chankov/agent-skills update`
+
+Reads the workspace's `.ai/agent-skills-setup.md`, compares the recorded
+package version against the installed package version, and prints the next
+step. The actual diff-aware refresh runs inside the coding agent via
+`/setup`.
+
+```bash
+# Upgrade the package itself first, then check the delta:
+npm install -g @chankov/agent-skills@latest
+npx agent-skills update --workspace .
+# Then open your agent and run /setup to review per-artifact diffs.
+```
+
+## Versioning
+
+The package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html):
+
+| Change | Bump |
+|---|---|
+| Skill removed, renamed, or its documented workflow changes; persona retired; command removed; install-record schema breakage | **major** |
+| New skill, new persona, new command, new option in an existing skill | **minor** |
+| Wording fix, doctor scan improvement, CLI bug fix | **patch** |
+
+### Pinning
+
+To pin a workspace to a specific version, install the package as a project
+dependency instead of using `npx`:
+
+```bash
+npm install --save-dev @chankov/agent-skills@1.4.2
+npx agent-skills init   # resolves to the pinned 1.4.2
+```
+
+Or pin globally:
+
+```bash
+npm install -g @chankov/agent-skills@1.4.2
+```
+
+### What "update" actually changes
+
+The package update is just `npm`'s usual upgrade. The interesting part runs
+inside the agent: `guided-workspace-setup` reads the `version:` line from
+`.ai/agent-skills-setup.md`, computes the delta against the current package
+version, and surfaces per-artifact `Status` based on a three-way diff:
+
+| Status | Means |
+|---|---|
+| `installed · upgrade available` | Source changed upstream; user copy still matches the old source → clean refresh |
+| `installed · conflicting upgrade` | Source changed upstream AND user modified the copy → three-way diff shown, write requires explicit consent |
+| `installed · removed upstream` | Artifact gone in the new version → proposed for deletion (subject to the removal-scope rule) |
+| `not installed · new in this version` | New artifact added in the new version → offered, marked `★` if recommended |
+
+The diff is sourced from `.versions/<recorded-version>/` inside the package —
+a snapshot the release pipeline writes for every published version.
+
+## Other install paths
+
+npm is the recommended path for most users. The other two stay supported:
+
+- **[Claude Code plugin marketplace](../README.md#quick-start)** — best UX
+  inside Claude Code. Same skills, marketplace-managed updates.
+- **Git clone + symlinks** — best for skill authors and contributors. Clone
+  the repo, run `/setup` from there, choose `symlink` in Step 8. Updates
+  flow through `git pull`. Symlinks need Developer Mode on Windows.
+
+All three paths converge on the same `guided-workspace-setup` skill — the
+difference is only in how the source files reach the workspace.
+
+## CI usage
+
+`npx @chankov/agent-skills init` is interactive by default (it prompts for
+the agent when detection is ambiguous). For CI, pass `--agent` explicitly:
+
+```bash
+npx --yes @chankov/agent-skills@latest init --agent claude-code --method copy --workspace .
+```
+
+`doctor` accepts `--yes` for non-interactive repair. Note that the
+LLM-driven `/setup` flow is not CI-runnable by design — confirmation gates
+exist precisely so a human approves every write.
+
+## Troubleshooting
+
+- **"Could not auto-detect your coding agent."** Pass `--agent` or run
+  `init` from a workspace that already has one of `.claude/`, `.opencode/`,
+  or `.pi/`.
+- **`update` says "no install record".** Run `init` once first; the install
+  record is what `update` reads.
+- **The version-aware menu shows `(snapshot missing)`.** The recorded version
+  is older than the snapshot retention in this package. The skill falls back
+  to "treat installed copy as canonical" — refresh manually if you want to
+  reset the baseline.

package/docs/opencode-setup.md

@@ -0,0 +1,241 @@
+# OpenCode Setup
+
+This guide explains how to use Agent Skills with OpenCode in a way that closely mirrors the Claude Code experience (automatic skill selection, lifecycle-driven workflows, and strict process enforcement).
+
+## Overview
+
+OpenCode supports custom `/commands`, but does not have a native plugin system or automatic skill routing like Claude Code.
+
+Instead, we achieve parity through:
+
+- A strong system prompt (`AGENTS.md`)
+- The built-in `skill` tool
+- Consistent skill discovery from the `/skills` directory
+- Optional prefixed slash commands from `.opencode/commands/`
+
+This creates an **agent-driven workflow** where skills are selected and executed automatically, with optional explicit lifecycle commands when you want them.
+
+This integration defaults to an agent-driven approach:
+
+- Skills are selected automatically based on intent
+- Workflows are enforced via `AGENTS.md`
+- Manual command invocation is optional, not required
+
+This more closely matches how Claude Code behaves in practice, while still allowing explicit OpenCode slash commands.
+
+---
+
+## Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/chankov/agent-skills.git
+```
+
+2. Install the global OpenCode configuration.
+
+Set `AGENT_SKILLS_DIR` to wherever you cloned the repo (used in the snippets below):
+
+```bash
+export AGENT_SKILLS_DIR="/path/to/agent-skills"
+```
+
+Add the repo's `AGENTS.md` to your global `~/.config/opencode/opencode.json` instructions list (replace `/path/to/agent-skills` with the absolute path on your machine — `~` is not expanded inside JSON):
+
+```json
+{
+  "instructions": [
+    "/path/to/agent-skills/AGENTS.md"
+  ],
+  "permission": {
+    "skill": {
+      "*": "allow"
+    }
+  }
+}
+```
+
+Link the skills and commands into your global OpenCode config directory. Symlinking individual files (rather than the whole directory) avoids replacing skills or commands you may already have installed from other sources:
+
+```bash
+mkdir -p ~/.config/opencode/skills ~/.config/opencode/commands
+
+# Skills: link each skill directory individually.
+for d in "$AGENT_SKILLS_DIR"/skills/*/; do
+  ln -s "$d" "$HOME/.config/opencode/skills/$(basename "$d")"
+done
+
+# Commands: link each command file individually.
+for f in "$AGENT_SKILLS_DIR"/.opencode/commands/*.md; do
+  ln -s "$f" "$HOME/.config/opencode/commands/$(basename "$f")"
+done
+```
+
+> ⚠️ If you already have `~/.config/opencode/skills` or `~/.config/opencode/commands` populated from other sources, do **not** replace the whole directory — use the per-file symlink approach above. The previous `ln -sfn <dir>` shortcut would silently overwrite the existing directory.
+
+3. Restart OpenCode.
+
+4. Open any project in OpenCode.
+
+5. The following Agent Skills assets are now available globally:
+
+- `AGENTS.md` instructions from the repo root
+- All skills from `skills/`
+- Optional prefixed slash commands from `.opencode/commands/`
+
+### Optional Slash Commands
+
+This repo ships OpenCode-native commands with an `as-` prefix so they are easy to distinguish from other commands:
+
+- `/as-spec`
+- `/as-plan`
+- `/as-build`
+- `/as-test`
+- `/as-review`
+- `/as-code-simplify`
+- `/as-ship`
+- `/as-design-agent`
+
+These commands are optional shortcuts. The agent can still invoke the correct skills automatically from plain natural-language requests.
+
+---
+
+## How It Works
+
+### 1. Skill Discovery
+
+All skills live in:
+
+```
+skills/<skill-name>/SKILL.md
+```
+
+OpenCode agents are instructed (via `AGENTS.md`) to:
+
+- Detect when a skill applies
+- Invoke the `skill` tool
+- Follow the skill exactly
+
+### 2. Automatic Skill Invocation
+
+The agent evaluates every request and maps it to the appropriate skill.
+
+Examples:
+
+- "build a feature" → `incremental-implementation` + `test-driven-development`
+- "design a system" → `spec-driven-development`
+- "fix a bug" → `debugging-and-error-recovery`
+- "review this code" → `code-review-and-quality`
+
+The user does **not** need to explicitly request skills.
+
+### 3. Lifecycle Mapping
+
+The development lifecycle is encoded implicitly via `AGENTS.md` and is also exposed through optional prefixed slash commands. Both routes invoke the same underlying skills:
+
+| Lifecycle phase | Claude Code command | OpenCode command   | Underlying skill(s)                                           |
+| --------------- | ------------------- | ------------------ | ------------------------------------------------------------- |
+| DEFINE          | `/spec`             | `/as-spec`         | `spec-driven-development`                                     |
+| PLAN            | `/plan`             | `/as-plan`         | `planning-and-task-breakdown`                                 |
+| BUILD           | `/build`            | `/as-build`        | `incremental-implementation` + `test-driven-development`      |
+| TEST            | `/test`             | `/as-test`         | `test-driven-development`                                     |
+| VERIFY          | —                   | —                  | `debugging-and-error-recovery` (implicit on failure)          |
+| REVIEW          | `/review`           | `/as-review`       | `code-review-and-quality`                                     |
+| SIMPLIFY        | `/code-simplify`    | `/as-code-simplify`| `code-simplification`                                         |
+| SHIP            | `/ship`             | `/as-ship`         | `shipping-and-launch`                                         |
+| AUTHOR          | `/design-agent`     | `/as-design-agent`     | `designing-agents`                                        |
+
+---
+
+## Usage Examples
+
+### Example 1: Feature Development
+
+User:
+```
+Add authentication to this app
+```
+
+Agent behavior:
+- Detects feature work
+- Invokes `spec-driven-development`
+- Produces a spec before writing code
+- Moves to planning and implementation skills
+
+---
+
+### Example 2: Bug Fix
+
+User:
+```
+This endpoint is returning 500 errors
+```
+
+Agent behavior:
+- Invokes `debugging-and-error-recovery`
+- Reproduces → localizes → fixes → adds guards
+
+---
+
+### Example 3: Code Review
+
+User:
+```
+Review this PR
+```
+
+Agent behavior:
+- Invokes `code-review-and-quality`
+- Applies structured review (correctness, design, readability, etc.)
+
+---
+
+## Agent Expectations (Critical)
+
+For OpenCode to work correctly, the agent must follow these rules:
+
+- Always check if a skill applies before acting
+- If a skill applies, it MUST be used
+- Never skip required workflows (spec, plan, test, etc.)
+- Do not jump directly to implementation
+
+These rules are enforced via `AGENTS.md`.
+
+---
+
+## Limitations
+
+- No plugin system (handled via prompt + structure)
+- Skill invocation depends on model compliance
+
+Despite these, the workflow closely matches Claude Code in practice.
+
+---
+
+## Recommended Workflow
+
+Just use natural language:
+
+- "Design a feature"
+- "Plan this change"
+- "Implement this"
+- "Fix this bug"
+- "Review this"
+
+The agent will automatically select and execute the correct skills.
+
+If you prefer explicit entry points, use the shipped slash commands such as `/as-spec`, `/as-plan`, or `/as-review`.
+
+---
+
+## Summary
+
+OpenCode integration works by combining:
+
+- Structured skills (this repo)
+- Strong agent rules (`AGENTS.md`)
+- Automatic skill invocation via reasoning
+- Optional `as-` prefixed slash commands for explicit lifecycle entry points
+
+This results in a **production-grade engineering workflow** that works both as an agent-driven system and as an explicit command-driven workflow.