agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/docs/skills/agileflow-docs/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: agileflow-docs
+version: 1.0.0
+category: agileflow/docs
+description: |
+  Use when the user wants to generate, update, or sync documentation:
+  API docs, README files, learning content, skill recommendations, or
+  architecture explanations. Also handles onboarding tours and glossary
+  definitions.
+triggers:
+  keywords:
+    - update docs
+    - write documentation
+    - readme
+    - api docs
+    - explain this
+    - how does this work
+    - glossary
+    - onboarding
+    - sync docs
+    - document this
+    - skill recommendation
+  priority: 45
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/docs.yaml
+  maxEntries: 30
+depends:
+  skills: []
+  plugins: [docs]
+---
+
+# AgileFlow Docs
+
+Documentation generator and learning assistant. Syncs READMEs,
+generates API docs, explains codebase concepts, and recommends skills
+for the current task.
+
+## When this skill activates
+
+- User asks to update or write documentation
+- User wants to understand how something works
+- User asks for a glossary definition or concept explanation
+- User wants to sync README after code changes
+- User asks which skill or command to use
+
+## Capabilities
+
+| Command                      | What it does                                    |
+| ---------------------------- | ----------------------------------------------- |
+| `/agileflow:docs`            | Sync docs after API or interface changes        |
+| `/agileflow:readme-sync`     | Update README to reflect current codebase state |
+| `/agileflow:learn`           | Explain AgileFlow concepts and patterns         |
+| `/agileflow:learn:explain`   | Deep-dive explanation of a specific concept     |
+| `/agileflow:learn:glossary`  | Define terms and acronyms                       |
+| `/agileflow:learn:tour`      | Onboarding tour of AgileFlow features           |
+| `/agileflow:learn:patterns`  | Common patterns and best practices              |
+| `/agileflow:skill:list`      | List available skills                           |
+| `/agileflow:skill:recommend` | Recommend the right skill for the current task  |
+
+## Auto-trigger rules
+
+Suggest `/agileflow:docs` after implementation when:
+
+- API endpoints or interfaces were added or changed
+- Public function signatures changed
+- New configuration options were added
+- README references stale commands or paths
+
+## Documentation quality checks
+
+- Does the README reflect the current install process?
+- Are all public APIs documented with examples?
+- Are new configuration options listed with their defaults?
+
+## Integration
+
+- **agileflow-engineering** — trigger docs after any implementation that changes public APIs, exports, or user-facing configuration; docs-sync is the last step of a well-run feature story
+- **agileflow-story-writer** — when writing a story, include "update docs" as an explicit acceptance criterion for API-changing work
+- **agileflow-seo** — after writing or updating public content, pass through seo for title, meta, heading, and structured data optimisation
+- **agileflow-delivery** — docs update is a delivery gate for API changes; delivery should block if docs are stale
+- **agileflow-pr-reviewer** — pr-reviewer checks that docs were updated alongside code; docs generates what the reviewer verifies
+- **agileflow-audit** — the completeness dimension of the audit flags missing docs; docs fills those gaps
+- **agileflow-research** — if writing technical docs for an unfamiliar pattern or library, use research first to gather authoritative source material
+- **agileflow-migration** — migration plans should be documented as runbooks; docs generates the runbook format after the migration plan is finalised
+
+## References
+
+Load these files when you need deeper context for the relevant task:
+
+| File                             | When to load                                                                              |
+| -------------------------------- | ----------------------------------------------------------------------------------------- |
+| `references/doc-types-guide.md`  | Deciding what kind of doc to write — tutorial vs how-to vs reference vs explanation       |
+| `references/api-doc-template.md` | Documenting an API endpoint or function — parameter tables, example requests, error cases |
+| `references/readme-template.md`  | Writing or auditing a README — required sections, what to include, what to skip           |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                       | When to follow                                                                            |
+| -------------------------- | ----------------------------------------------------------------------------------------- |
+| `workflows/sync.md`        | User wants to sync docs after implementation — checks what changed, updates relevant docs |
+| `workflows/readme-sync.md` | User wants to update the README — audits current state, fills gaps                        |

package/content/plugins/docs/skills/agileflow-docs/references/api-doc-template.md

@@ -0,0 +1,167 @@
+# API Documentation Template
+
+**Load this when:** Writing or reviewing API reference documentation for REST endpoints, SDK methods, or CLI commands.
+
+## REST Endpoint Template
+
+````markdown
+## [METHOD] /path/to/endpoint
+
+[One sentence describing what this endpoint does.]
+
+**Authentication:** Bearer token | API key | None  
+**Rate limit:** N requests/minute per [user/org/IP]
+
+### Path Parameters
+
+| Parameter | Type   | Required | Description                       |
+| --------- | ------ | -------- | --------------------------------- |
+| `id`      | string | Yes      | Unique identifier of the resource |
+
+### Query Parameters
+
+| Parameter | Type    | Required | Default | Description                              |
+| --------- | ------- | -------- | ------- | ---------------------------------------- |
+| `limit`   | integer | No       | 20      | Max results to return (1–100)            |
+| `cursor`  | string  | No       | —       | Pagination cursor from previous response |
+| `filter`  | string  | No       | —       | Filter expression (see Filter Syntax)    |
+
+### Request Body
+
+Content-Type: `application/json`
+
+| Field            | Type    | Required | Description                           |
+| ---------------- | ------- | -------- | ------------------------------------- |
+| `name`           | string  | Yes      | Display name (max 255 chars)          |
+| `config`         | object  | No       | Optional configuration overrides      |
+| `config.timeout` | integer | No       | Request timeout in ms (default: 5000) |
+
+### Request Example
+
+\```bash
+curl -X POST https://api.example.com/v1/resources \
+ -H "Authorization: Bearer $TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+"name": "my-resource",
+"config": { "timeout": 3000 }
+}'
+\```
+
+### Response
+
+**200 OK**
+\```json
+{
+"id": "res_abc123",
+"name": "my-resource",
+"status": "active",
+"createdAt": "2025-01-15T10:30:00Z",
+"config": {
+"timeout": 3000
+}
+}
+\```
+
+### Response Fields
+
+| Field       | Type     | Description                     |
+| ----------- | -------- | ------------------------------- |
+| `id`        | string   | Unique resource identifier      |
+| `name`      | string   | Display name                    |
+| `status`    | enum     | `active`, `inactive`, `pending` |
+| `createdAt` | ISO 8601 | Creation timestamp              |
+
+### Error Responses
+
+| Status | Code              | Description                             |
+| ------ | ----------------- | --------------------------------------- |
+| 400    | `INVALID_REQUEST` | Missing required field or invalid value |
+| 401    | `UNAUTHORIZED`    | Invalid or expired token                |
+| 403    | `FORBIDDEN`       | Insufficient permissions                |
+| 404    | `NOT_FOUND`       | Resource does not exist                 |
+| 409    | `CONFLICT`        | Resource with this name already exists  |
+| 429    | `RATE_LIMITED`    | Too many requests                       |
+| 500    | `SERVER_ERROR`    | Unexpected server error                 |
+
+**Error response format:**
+\```json
+{
+"error": {
+"code": "INVALID_REQUEST",
+"message": "Field 'name' is required",
+"field": "name"
+}
+}
+\```
+````
+
+---
+
+## SDK Method Template
+
+````markdown
+### `client.resources.create(options)`
+
+Creates a new resource.
+
+**Parameters:**
+
+| Parameter        | Type             | Required | Description             |
+| ---------------- | ---------------- | -------- | ----------------------- |
+| `options.name`   | `string`         | Yes      | Display name            |
+| `options.config` | `ResourceConfig` | No       | Configuration overrides |
+
+**Returns:** `Promise<Resource>`
+
+**Throws:**
+
+- `ValidationError` — if required fields are missing
+- `ConflictError` — if name already in use
+- `ApiError` — on server-side errors
+
+**Example:**
+\```typescript
+const resource = await client.resources.create({
+name: "my-resource",
+config: { timeout: 3000 }
+});
+console.log(resource.id); // "res_abc123"
+\```
+````
+
+---
+
+## Documentation Quality Checklist
+
+- [ ] Every parameter documented with type, required flag, and description
+- [ ] At least one working request example per endpoint
+- [ ] All possible error responses listed
+- [ ] Enums list all valid values
+- [ ] Authentication requirements stated
+- [ ] Rate limits specified
+- [ ] Pagination explained (if applicable)
+- [ ] Deprecated fields/methods marked with deprecation notice
+- [ ] Version added / version removed noted on fields
+
+---
+
+## Deprecation Notice Format
+
+```markdown
+> **Deprecated:** The `oldField` parameter is deprecated as of v2.3 and will be
+> removed in v3.0. Use `newField` instead. [Migration guide](#migration)
+```
+
+---
+
+## Versioning in URLs vs Headers
+
+| Strategy      | URL example            | Header example                               |
+| ------------- | ---------------------- | -------------------------------------------- |
+| URL path      | `/v1/resources`        | —                                            |
+| Query param   | `/resources?version=1` | —                                            |
+| Accept header | —                      | `Accept: application/vnd.api+json;version=1` |
+| Custom header | —                      | `API-Version: 2025-01-01`                    |
+
+Recommendation: URL path versioning for REST — most explicit, most cache-friendly.

package/content/plugins/docs/skills/agileflow-docs/references/doc-types-guide.md

@@ -0,0 +1,141 @@
+# Documentation Types Guide
+
+**Load this when:** deciding what kind of documentation to write, choosing
+a format for a given audience, or auditing whether docs are complete.
+
+## The four types of documentation
+
+(Divio documentation system — each type has a distinct purpose and format)
+
+| Type             | Answers                     | Analogy                  | User's goal                |
+| ---------------- | --------------------------- | ------------------------ | -------------------------- |
+| **Tutorial**     | "Help me learn"             | Teaching a child to cook | Learning by doing          |
+| **How-to guide** | "How do I do X?"            | Recipe                   | Solving a specific problem |
+| **Reference**    | "What is X?"                | Encyclopedia             | Looking something up       |
+| **Explanation**  | "Why does X work this way?" | Essay                    | Understanding concepts     |
+
+### Tutorial
+
+- **Goal**: Learning by doing
+- **Format**: Step-by-step walkthrough with expected output at each step
+- **Tone**: Teacher-led. "We'll now add a user to the database."
+- **Don't**: Explain why things work. Just do the thing.
+
+```markdown
+## Getting Started
+
+In this tutorial, you'll build a simple task list API from scratch.
+By the end, you'll have a working endpoint that stores and retrieves tasks.
+
+### Step 1: Create the project
+
+Run the following command to scaffold your project:
+\`\`\`bash
+npx create-api my-tasks
+cd my-tasks
+\`\`\`
+
+You should see output like:
+\`\`\`
+✓ Project created
+✓ Dependencies installed
+\`\`\`
+```
+
+### How-to guide
+
+- **Goal**: Accomplish a specific task the reader already understands
+- **Format**: Numbered steps. Assumes context.
+- **Tone**: Direct. "Do X. Then do Y."
+- **Don't**: Teach concepts. Reference the explanation doc instead.
+
+```markdown
+## How to add a custom webhook
+
+1. Open **Settings → Integrations**
+2. Click **Add webhook**
+3. Enter the destination URL
+4. Select which events to send
+5. Click **Save**
+
+To verify delivery, check **Settings → Delivery log**.
+```
+
+### Reference
+
+- **Goal**: Accurate, complete information to look up
+- **Format**: Tables, parameter lists, type definitions
+- **Tone**: Neutral, dense, no narrative
+- **Don't**: Add tutorials or explanations. Just the facts.
+
+```markdown
+## `deliver(payload, options)`
+
+Delivers a payload to all configured channels.
+
+**Parameters:**
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `payload` | `object` | Yes | — | The data to deliver |
+| `options.retries` | `number` | No | `3` | Max retry attempts |
+| `options.timeout` | `number` | No | `5000` | Timeout in ms |
+
+**Returns:** `Promise<DeliveryResult>`
+```
+
+### Explanation
+
+- **Goal**: Understanding — the "why" behind decisions
+- **Format**: Prose. Can include diagrams, comparisons, history.
+- **Tone**: Thoughtful. "We chose X because..."
+- **Don't**: Include step-by-step instructions.
+
+```markdown
+## Why we use event sourcing for delivery state
+
+Delivery systems face a fundamental problem: at-least-once vs at-most-once
+delivery. We chose at-least-once with idempotency keys because...
+```
+
+## Choosing the right type
+
+| User says...                            | Write this               |
+| --------------------------------------- | ------------------------ |
+| "I'm new to X, where do I start?"       | Tutorial                 |
+| "How do I configure Y?"                 | How-to guide             |
+| "What parameters does Z accept?"        | Reference                |
+| "Why does the system do X this way?"    | Explanation              |
+| "I want to understand the architecture" | Explanation              |
+| "Show me an example of X"               | How-to guide or Tutorial |
+
+## Common documentation mistakes
+
+| Mistake                       | Problem                     | Fix                                 |
+| ----------------------------- | --------------------------- | ----------------------------------- |
+| Tutorial that explains theory | Breaks learning flow        | Move explanations to a separate doc |
+| How-to with "why it works"    | Reader just wants the steps | Strip the explanation               |
+| Reference with narrative      | Hard to scan                | Tables and lists only               |
+| No examples in reference      | Too abstract                | Add one example per concept         |
+| Explanation with step-by-step | Wrong register              | Move steps to how-to                |
+
+## API documentation checklist
+
+For every public function/endpoint:
+
+```
+⬜ Description (one sentence, active voice)
+⬜ All parameters documented (name, type, required, default, description)
+⬜ Return value documented (type + shape)
+⬜ At least one example
+⬜ Error cases documented (what throws, what returns null)
+⬜ Side effects noted (if any)
+⬜ Version added / deprecated (if applicable)
+```
+
+## Docs-as-code practices
+
+- Write docs in the same PR as the code change
+- Docs live in the repo alongside the code they document
+- Use the same review process as code
+- Broken docs = broken code: treat them with equal priority
+- Auto-generate reference docs from code comments where possible (JSDoc → TypeDoc)

package/content/plugins/docs/skills/agileflow-docs/references/readme-template.md

@@ -0,0 +1,156 @@
+# README Template
+
+**Load this when:** Writing or auditing a project README — what sections to include, what to skip, and what to prioritize.
+
+## README Section Order (recommended)
+
+```
+1. Name + one-line description
+2. Badges (CI, npm, license) — optional
+3. Screenshot or demo GIF — if visual tool
+4. Quick start / install
+5. Usage (most common case)
+6. Configuration (if non-trivial)
+7. API reference (or link to docs)
+8. Contributing
+9. License
+```
+
+---
+
+## Section Templates
+
+### Name + Description
+
+```markdown
+# package-name
+
+[One sentence: what it does and who it's for. No filler words.]
+
+> Minimal task queue for Node.js with Redis. Zero dependencies beyond ioredis.
+```
+
+### Badges
+
+```markdown
+[![CI](https://github.com/org/repo/actions/workflows/ci.yml/badge.svg)](...)
+[![npm](https://img.shields.io/npm/v/package-name)](https://npmjs.com/package/package-name)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+```
+
+Keep badges to 3–5 max. Remove badges that are always red.
+
+### Quick Start
+
+````markdown
+## Quick Start
+
+\```bash
+npm install package-name
+\```
+
+\```js
+import { thing } from 'package-name';
+const result = await thing({ option: 'value' });
+\```
+
+That's it. [See full usage →](#usage)
+````
+
+### Usage
+
+```markdown
+## Usage
+
+### Most common case
+
+[Show the code people will actually write. Real example, not `foo/bar`.]
+
+### With options
+
+[Show the next most common usage pattern.]
+
+### Edge cases / advanced
+
+[Keep this short or link to docs.]
+```
+
+### Configuration
+
+```markdown
+## Configuration
+
+| Option    | Type    | Default | Description           |
+| --------- | ------- | ------- | --------------------- |
+| `timeout` | number  | `5000`  | Request timeout in ms |
+| `retries` | number  | `3`     | Max retry attempts    |
+| `verbose` | boolean | `false` | Log debug output      |
+```
+
+### Contributing
+
+````markdown
+## Contributing
+
+\```bash
+git clone https://github.com/org/repo
+npm install
+npm test
+\```
+
+PRs welcome. Please open an issue first for significant changes.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+````
+
+---
+
+## What to Include
+
+| Include                          | Reason                            |
+| -------------------------------- | --------------------------------- |
+| Install command                  | First thing people need           |
+| Working code example             | Proves it's real                  |
+| Node/runtime version requirement | Prevents frustration              |
+| License                          | Legal requirement for open source |
+| Link to changelog                | Release history                   |
+| Link to issues                   | Support channel                   |
+
+---
+
+## What to Skip
+
+| Skip                                  | Why                                       |
+| ------------------------------------- | ----------------------------------------- |
+| Long introductory prose               | Nobody reads it                           |
+| "This project was created because..." | Unnecessary backstory                     |
+| Detailed philosophy section           | Put in docs, not README                   |
+| Exhaustive API reference              | Belongs in `/docs` or generated reference |
+| TODO list                             | Put in issues                             |
+| "Built with ❤️" filler                | Adds nothing                              |
+| >5 badges                             | Visual clutter                            |
+
+---
+
+## README Antipatterns
+
+| Antipattern                                | Fix                                       |
+| ------------------------------------------ | ----------------------------------------- |
+| Install section buried below 3 paragraphs  | Move install to top                       |
+| Example uses `example.com` / `foo` / `bar` | Use realistic domain example              |
+| "See the docs" with no link                | Add the actual link                       |
+| Out-of-date version in examples            | Pin examples to major version only (`^1`) |
+| Missing minimum Node/runtime version       | Add to install section                    |
+| Screenshot from 2 major versions ago       | Update or remove                          |
+
+---
+
+## README Length Guidelines
+
+| Project type     | Target length                     |
+| ---------------- | --------------------------------- |
+| CLI tool         | 100–200 lines                     |
+| npm library      | 150–300 lines                     |
+| Full application | 100–200 lines + link to docs site |
+| Internal tool    | 50–100 lines                      |
+
+**Rule:** If the README is longer than 400 lines, extract to a docs site.

package/content/plugins/docs/skills/agileflow-docs/workflows/readme-sync.md

@@ -0,0 +1,57 @@
+# README Sync Workflow — Folder README Update
+
+**Triggers:** "sync README", "update the README for docs/", "README doesn't match the folder contents", "generate contents section", "README for all docs folders"
+
+**Goal:** Update the `## Contents` section of a folder's `README.md` to match its actual files and subdirectories — without touching any other sections.
+
+## Inputs needed
+
+| Input       | Required | How to get it                                                         |
+| ----------- | -------- | --------------------------------------------------------------------- |
+| folder path | Yes      | Ask: "Which folder should I sync? (e.g., docs/02-practices or 'all')" |
+
+## Steps
+
+1. If the folder is not specified, ask: "Which folder should I sync?" Options: [A] `docs/02-practices` (recommended), [B] `docs/04-architecture`, [C] `all` — sync every subfolder under `docs/`, [D] Enter a different path.
+
+2. For each target folder:
+   a. List all files and subdirectories in the folder.
+   b. For each file, extract a brief description by reading the first `# ` header or the first non-empty sentence in the file.
+   c. For each subdirectory, read its `README.md` first line or directory name.
+
+3. Build the new `## Contents` section:
+
+   ```markdown
+   ## Contents
+
+   | File                         | Description                  |
+   | ---------------------------- | ---------------------------- |
+   | [filename.md](./filename.md) | Brief description            |
+   | [subfolder/](./subfolder/)   | What this subfolder contains |
+   ```
+
+4. Read the existing `README.md`. Find the `## Contents` section boundaries. Show the user the proposed change (what is currently in the section vs. what the new section will be).
+
+5. Ask: [A] Update the Contents section (recommended), [B] Make changes first, [C] Skip this folder.
+
+6. If confirmed, update only the `## Contents` section using Edit — do not modify any other section of the README.
+
+7. If `all` was specified, repeat for every subfolder under `docs/`. Process them in parallel.
+
+8. Report: N folders updated, M folders already up to date, K folders skipped.
+
+## Output
+
+Updated `## Contents` section in the target README(s). All other sections preserved unchanged.
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number. Example:
+
+```
+How would you like to proceed?
+1. Save and continue
+2. Review before saving
+3. Discard
+```

package/content/plugins/docs/skills/agileflow-docs/workflows/sync.md

@@ -0,0 +1,64 @@
+# Sync Workflow — Documentation Synchronization
+
+**Triggers:** "sync docs", "update documentation", "my docs are out of date", "documentation drift", "docs don't match the code", "generate docs from code changes"
+
+**Goal:** Compare code changes against expected documentation, identify gaps, and update or create documentation to reflect the current state of the codebase.
+
+## Inputs needed
+
+| Input       | Required | How to get it                                  |
+| ----------- | -------- | ---------------------------------------------- |
+| branch      | No       | Default: current branch                        |
+| base        | No       | Default: `main`                                |
+| auto-create | No       | Default: false — ask before creating new files |
+
+## Steps
+
+1. Run `git diff <base>...<branch> --name-status` to get changed files. If no base/branch provided, diff against `main`.
+
+2. Categorize each changed file:
+   - **API endpoints**: `src/api/`, `src/routes/`, `src/controllers/`
+   - **UI components**: `src/components/`, `src/pages/`
+   - **Services/utils**: `src/services/`, `src/utils/`
+   - **Config**: `*.config.js`, `*.yml`, `.env.example`
+   - **Database**: `migrations/`, `schema/`
+
+3. For each changed file, map to the expected documentation location:
+   - New API endpoint → check section in `docs/04-architecture/api.md`
+   - New UI component → check `docs/04-architecture/components.md`
+   - New service → check `docs/04-architecture/services.md`
+   - Config change → check `docs/02-practices/configuration.md`
+   - DB migration → check `docs/04-architecture/database.md`
+
+4. Check each expected doc location. Infer content from TypeScript types, JSDoc comments, OpenAPI annotations, and test descriptions when docs are missing.
+
+5. Generate a gap report:
+
+   ```
+   | File Changed | Expected Doc | Status |
+   |--------------|-------------|--------|
+   | src/api/users.ts | docs/04-architecture/api.md | Missing section |
+   | src/components/Button.tsx | docs/04-architecture/components.md | Up to date |
+   ```
+
+6. Present the gap report. Ask the user: [A] Auto-create/update all missing docs (recommended), [B] Show me each gap and I'll decide, [C] Just report — I'll update docs manually.
+
+7. For each doc that needs updating, show the proposed content change before writing. Use managed section markers to preserve any custom content the user has added.
+
+8. After all updates, show a summary: N docs updated, M docs created, K docs already up to date. Never delete documentation without explicit user approval.
+
+## Output
+
+Gap report with status for each changed file. Updated documentation files. Never removes existing content — only adds or updates managed sections.
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number. Example:
+
+```
+How would you like to proceed?
+1. Save and continue
+2. Review before saving
+3. Discard
+```