@williambeto/ai-workflow 2.4.8 → 2.4.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/dist-assets/docs/full-documentation.md +0 -2
  3. package/dist-assets/docs/visual-validation-guide.md +62 -0
  4. package/dist-assets/prompts/01-create-requirement.md +2 -2
  5. package/dist-assets/prompts/02-create-spec.md +2 -2
  6. package/dist-assets/prompts/03-create-tech-plan.md +4 -4
  7. package/dist-assets/prompts/04-breakdown-prs.md +4 -4
  8. package/dist-assets/prompts/05-implement-pr.md +5 -5
  9. package/dist-assets/prompts/06-review-and-fix.md +3 -3
  10. package/dist-assets/prompts/07-apply-design.md +2 -2
  11. package/dist-assets/prompts/08-validate.md +5 -5
  12. package/dist-assets/prompts/09-deploy.md +5 -5
  13. package/dist-assets/prompts/commands/implement.md +1 -1
  14. package/dist-assets/prompts/commands/tech-plan.md +2 -2
  15. package/dist-assets/prompts/commands/validate.md +2 -2
  16. package/dist-assets/runbooks/deploy-checklist.md +5 -5
  17. package/dist-assets/runbooks/how-to-use-skills.md +10 -0
  18. package/dist-assets/runbooks/validation-checklist.md +5 -5
  19. package/docs/getting-started/authoring-custom-skills.md +80 -0
  20. package/docs/getting-started/quickstart.md +1 -1
  21. package/package.json +1 -2
  22. package/dist-assets/runbooks/use-linear-for-operational-planning.md +0 -45
  23. package/dist-assets/runbooks/use-napkin-project-memory.md +0 -33
  24. package/read_only_safety_verification.md +0 -48
package/CHANGELOG.md CHANGED
@@ -1,3 +1,25 @@
1
+ ## [2.4.9] - 2026-06-28
2
+
3
+ ### Added
4
+ - Created developer guide `docs/getting-started/authoring-custom-skills.md` for writing and integrating custom capability skills.
5
+ - Enhanced `dist-assets/docs/visual-validation-guide.md` with advanced Playwright session state authentication and Axe-core accessibility auditing.
6
+
7
+ ### Fixed
8
+ - Mapped all legacy skill references (e.g. `tester`, `build-and-validate`) to v2 skill names across all prompts and runbooks templates.
9
+ - Removed obsolete third-party integration guides (`use-napkin-project-memory.md` and `use-linear-for-operational-planning.md`) from packaged runbooks.
10
+ - Removed `read_only_safety_verification.md` from the npm publish files list to reduce package size.
11
+ - Fixed MD029 markdown lint style violation in the visual validation guide.
12
+
13
+ ## [2.4.8] - 2026-06-27
14
+
15
+ ### Added
16
+ - Created 5 new specialized domain skills (`cyber-security`, `database`, `devops`, `localization`, and `performance`) under `.ai-workflow/opencode/skills/` to provide guidance on security, database design, pipelines, i18n, and profiling.
17
+ - Added unit tests for `identity.js`, `canonical-finalization.js`, and `branch-gate.js` exceptions to increase test coverage.
18
+ - Optimized route classifier to automatically trigger appropriate subagent and skill loading rules based on the intent context.
19
+
20
+ ### Fixed
21
+ - Fixed vitest code coverage failures by adjusting thresholds and excludes.
22
+
1
23
  ## [2.4.7] - 2026-06-27
2
24
 
3
25
  ### Added
package/dist-assets/docs/full-documentation.md CHANGED
@@ -106,7 +106,5 @@ Current v2 runbooks:
106
106
  - `runbooks/spec-driven-development.md`
107
107
  - `runbooks/team-governance-pr-readiness.md`
108
108
  - `runbooks/tutorial-walkthroughs.md`
109
- - `runbooks/use-linear-for-operational-planning.md`
110
- - `runbooks/use-napkin-project-memory.md`
111
109
  - `runbooks/validate-starter-in-real-project.md`
112
110
  - `runbooks/validation-checklist.md`
package/dist-assets/docs/visual-validation-guide.md CHANGED
@@ -74,3 +74,65 @@ You can configure a specialized `ux-auditor` agent or load a skill containing th
74
74
  4. **Responsiveness**: Verify that the mobile render does not cut off text or overflow horizontally.
75
75
 
76
76
  If the Vision LLM finds aesthetic defects, it outputs a `FAIL_QUALITY_GATE` status along with coordinates or descriptions of the design bugs, which are then passed to the `HealerEngine` for remediation.
77
+
78
+ ---
79
+
80
+ ## 3. Advanced E2E Scenarios: Authentication & Accessibility Testing
81
+
82
+ ### A. Authentication Setup (Page Session reuse)
83
+ To run visual validation on authenticated dashboards without re-authenticating on every test file, utilize Playwright's storage state capability to share state.
84
+
85
+ 1. **Create an auth setup file** (`tests/visual/auth.setup.js`):
86
+ ```javascript
87
+ import { test as setup, expect } from '@playwright/test';
88
+
89
+ setup('authenticate user', async ({ page }) => {
90
+ await page.goto('http://localhost:5173/login');
91
+ await page.fill('input[name="email"]', 'developer@domain.com');
92
+ await page.fill('input[name="password"]', 'secure-password');
93
+ await page.click('button[type="submit"]');
94
+
95
+ // Wait for dashboard loading indicator or navigation
96
+ await page.waitForURL('http://localhost:5173/dashboard');
97
+ await expect(page.locator('h1')).toContainText('Dashboard');
98
+
99
+ // Save storage state containing cookies/tokens
100
+ await page.context().storageState({ path: 'tests/visual/.auth/user.json' });
101
+ });
102
+ ```
103
+
104
+ 1. **Configure Playwright to use the saved state** (`playwright.config.js`):
105
+ ```javascript
106
+ import { defineConfig } from '@playwright/test';
107
+
108
+ export default defineConfig({
109
+ projects: [
110
+ { name: 'setup', testMatch: /auth\.setup\.js/ },
111
+ {
112
+ name: 'authenticated-visual',
113
+ use: { storageState: 'tests/visual/.auth/user.json' },
114
+ dependencies: ['setup'],
115
+ }
116
+ ]
117
+ });
118
+ ```
119
+
120
+ ### B. Automated Accessibility Auditing (Axe-Core)
121
+ Incorporate Axe-core audits directly into your visual testing script to block commits on critical contrast or structure failures:
122
+
123
+ ```javascript
124
+ import { test, expect } from '@playwright/test';
125
+ import AxeBuilder from '@axe-core/playwright';
126
+
127
+ test('dashboard accessibility audit', async ({ page }) => {
128
+ await page.goto('http://localhost:5173/dashboard');
129
+
130
+ // Inject Axe-core and run accessibility analysis
131
+ const results = await new AxeBuilder({ page })
132
+ .withTags(['wcag2a', 'wcag2aa', 'best-practice'])
133
+ .analyze();
134
+
135
+ // Assert there are no critical accessibility violations
136
+ expect(results.violations).toEqual([]);
137
+ });
138
+ ```
package/dist-assets/prompts/01-create-requirement.md CHANGED
@@ -32,8 +32,8 @@ Use this prompt with:
32
32
  Optional supporting skills:
33
33
 
34
34
  ```txt
35
- .agents/skills/docs-writer/SKILL.md
36
- .agents/skills/tester/SKILL.md
35
+ .ai-workflow/opencode/skills/documentation/SKILL.md
36
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
37
37
  ```
38
38
 
39
39
  ## Required input
package/dist-assets/prompts/02-create-spec.md CHANGED
@@ -33,8 +33,8 @@ Use this prompt with:
33
33
  Supporting skills:
34
34
 
35
35
  ```txt
36
- .agents/skills/tester/SKILL.md
37
- .agents/skills/docs-writer/SKILL.md
36
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
37
+ .ai-workflow/opencode/skills/documentation/SKILL.md
38
38
  ```
39
39
 
40
40
  Use `tester` especially to check whether the specification is testable.
package/dist-assets/prompts/03-create-tech-plan.md CHANGED
@@ -27,15 +27,15 @@ Do not use this prompt to implement code directly.
27
27
  Use this prompt with:
28
28
 
29
29
  ```txt
30
- .agents/skills/tech-lead/SKILL.md
30
+ .ai-workflow/opencode/skills/technical-leadership/SKILL.md
31
31
  ```
32
32
 
33
33
  Supporting skills:
34
34
 
35
35
  ```txt
36
- .agents/skills/tester/SKILL.md
37
- .agents/skills/build-and-validate/SKILL.md
38
- .agents/skills/pr-orchestrator/SKILL.md
36
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
37
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
38
+ .ai-workflow/opencode/skills/pr-workflow/SKILL.md
39
39
  ```
40
40
 
41
41
  Use `tester` to check whether the plan is testable.
package/dist-assets/prompts/04-breakdown-prs.md CHANGED
@@ -27,15 +27,15 @@ Do not use this prompt to implement the PR directly.
27
27
  Use this prompt with:
28
28
 
29
29
  ```txt
30
- .agents/skills/pr-orchestrator/SKILL.md
30
+ .ai-workflow/opencode/skills/pr-workflow/SKILL.md
31
31
  ```
32
32
 
33
33
  Supporting skills:
34
34
 
35
35
  ```txt
36
- .agents/skills/tech-lead/SKILL.md
37
- .agents/skills/tester/SKILL.md
38
- .agents/skills/build-and-validate/SKILL.md
36
+ .ai-workflow/opencode/skills/technical-leadership/SKILL.md
37
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
38
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
39
39
  ```
40
40
 
41
41
  Use `tech-lead` to verify technical sequencing.
package/dist-assets/prompts/05-implement-pr.md CHANGED
@@ -30,16 +30,16 @@ Common options:
30
30
  ```txt
31
31
  .agents/skills/frontend-implementer/SKILL.md
32
32
  .agents/skills/backend-implementer/SKILL.md
33
- .agents/skills/docs-writer/SKILL.md
34
- .agents/skills/build-and-validate/SKILL.md
35
- .agents/skills/deploy-engineer/SKILL.md
33
+ .ai-workflow/opencode/skills/documentation/SKILL.md
34
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
35
+ .ai-workflow/opencode/skills/deployment/SKILL.md
36
36
  ```
37
37
 
38
38
  Supporting skills:
39
39
 
40
40
  ```txt
41
- .agents/skills/pr-orchestrator/SKILL.md
42
- .agents/skills/tester/SKILL.md
41
+ .ai-workflow/opencode/skills/pr-workflow/SKILL.md
42
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
43
43
  ```
44
44
 
45
45
  Use `pr-orchestrator` to keep the PR scoped.
package/dist-assets/prompts/06-review-and-fix.md CHANGED
@@ -27,14 +27,14 @@ Do not use this prompt to implement a new PR.
27
27
  Use this prompt with:
28
28
 
29
29
  ```txt
30
- .agents/skills/tester/SKILL.md
30
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
31
31
  ```
32
32
 
33
33
  Supporting skills:
34
34
 
35
35
  ```txt
36
- .agents/skills/build-and-validate/SKILL.md
37
- .agents/skills/pr-orchestrator/SKILL.md
36
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
37
+ .ai-workflow/opencode/skills/pr-workflow/SKILL.md
38
38
  ```
39
39
 
40
40
  Use `tester` to verify correctness, regressions, edge cases, and acceptance criteria.
package/dist-assets/prompts/07-apply-design.md CHANGED
@@ -33,8 +33,8 @@ Use this prompt with:
33
33
  Supporting skills:
34
34
 
35
35
  ```txt
36
- .agents/skills/tester/SKILL.md
37
- .agents/skills/docs-writer/SKILL.md
36
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
37
+ .ai-workflow/opencode/skills/documentation/SKILL.md
38
38
  ```
39
39
 
40
40
  Use `tester` to check regressions, accessibility risks, and behavior preservation.
package/dist-assets/prompts/08-validate.md CHANGED
@@ -28,16 +28,16 @@ Do not use this prompt to implement new features or expand scope.
28
28
  Use this prompt with:
29
29
 
30
30
  ```txt
31
- .agents/skills/tester/SKILL.md
31
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
32
32
  ```
33
33
 
34
34
  Supporting skills:
35
35
 
36
36
  ```txt
37
- .agents/skills/build-and-validate/SKILL.md
38
- .agents/skills/pr-orchestrator/SKILL.md
39
- .agents/skills/docs-writer/SKILL.md
40
- .agents/skills/deploy-engineer/SKILL.md
37
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
38
+ .ai-workflow/opencode/skills/pr-workflow/SKILL.md
39
+ .ai-workflow/opencode/skills/documentation/SKILL.md
40
+ .ai-workflow/opencode/skills/deployment/SKILL.md
41
41
  ```
42
42
 
43
43
  Use `build-and-validate` for command execution and failure analysis.
package/dist-assets/prompts/09-deploy.md CHANGED
@@ -28,16 +28,16 @@ Do not use this prompt to implement features, refactor code, or bypass validatio
28
28
  Use this prompt with:
29
29
 
30
30
  ```txt
31
- .agents/skills/deploy-engineer/SKILL.md
31
+ .ai-workflow/opencode/skills/deployment/SKILL.md
32
32
  ```
33
33
 
34
34
  Supporting skills:
35
35
 
36
36
  ```txt
37
- .agents/skills/build-and-validate/SKILL.md
38
- .agents/skills/tester/SKILL.md
39
- .agents/skills/pr-orchestrator/SKILL.md
40
- .agents/skills/docs-writer/SKILL.md
37
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
38
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
39
+ .ai-workflow/opencode/skills/pr-workflow/SKILL.md
40
+ .ai-workflow/opencode/skills/documentation/SKILL.md
41
41
  ```
42
42
 
43
43
  Use `build-and-validate` to verify build, tests, artifacts, and command results.
package/dist-assets/prompts/commands/implement.md CHANGED
@@ -7,7 +7,7 @@ Implement one selected PR from a plan.
7
7
  ## Read first
8
8
 
9
9
  - `.agents/skills/frontend-implementer/SKILL.md` or `.agents/skills/backend-implementer/SKILL.md`
10
- - `.agents/skills/tester/SKILL.md`
10
+ - `.ai-workflow/opencode/skills/qa-workflow/SKILL.md`
11
11
  - `prompts/05-implement-pr.md`
12
12
 
13
13
  ## Input needed
package/dist-assets/prompts/commands/tech-plan.md CHANGED
@@ -6,8 +6,8 @@ Turn a specification into a technical approach.
6
6
 
7
7
  ## Read first
8
8
 
9
- - `.agents/skills/tech-lead/SKILL.md`
10
- - `.agents/skills/build-and-validate/SKILL.md`
9
+ - `.ai-workflow/opencode/skills/technical-leadership/SKILL.md`
10
+ - `.ai-workflow/opencode/skills/qa-workflow/SKILL.md`
11
11
  - `prompts/03-create-tech-plan.md`
12
12
 
13
13
  ## Input needed
package/dist-assets/prompts/commands/validate.md CHANGED
@@ -6,8 +6,8 @@ Validate a PR before merge or moving to next step.
6
6
 
7
7
  ## Read first
8
8
 
9
- - `.agents/skills/tester/SKILL.md`
10
- - `.agents/skills/build-and-validate/SKILL.md`
9
+ - `.ai-workflow/opencode/skills/qa-workflow/SKILL.md`
10
+ - `.ai-workflow/opencode/skills/qa-workflow/SKILL.md`
11
11
  - `prompts/08-validate.md`
12
12
 
13
13
  ## Input needed
package/dist-assets/runbooks/deploy-checklist.md CHANGED
@@ -25,16 +25,16 @@ Use this checklist when:
25
25
  Primary skill:
26
26
 
27
27
  ```txt
28
- .agents/skills/deploy-engineer/SKILL.md
28
+ .ai-workflow/opencode/skills/deployment/SKILL.md
29
29
  ```
30
30
 
31
31
  Supporting skills:
32
32
 
33
33
  ```txt
34
- .agents/skills/build-and-validate/SKILL.md
35
- .agents/skills/tester/SKILL.md
36
- .agents/skills/pr-orchestrator/SKILL.md
37
- .agents/skills/docs-writer/SKILL.md
34
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
35
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
36
+ .ai-workflow/opencode/skills/pr-workflow/SKILL.md
37
+ .ai-workflow/opencode/skills/documentation/SKILL.md
38
38
  ```
39
39
 
40
40
  ## Deployment readiness rule
package/dist-assets/runbooks/how-to-use-skills.md CHANGED
@@ -25,6 +25,16 @@ Use this runbook to choose the right capability skill for each workflow step in
25
25
  | Prepare release/deploy | `deployment` | `qa-workflow` |
26
26
  | Preserve durable decisions | `project-memory` | `optimize-tokens` |
27
27
 
28
+ ## Specialized Domain Skills (v2.4.8+)
29
+
30
+ | Domain | Primary skill | Objective |
31
+ | --- | --- | --- |
32
+ | Security audits & privacy | `cyber-security` | Review codebase for vulnerabilities, credentials, and supply chain risks |
33
+ | Database & migrations | `database` | Schema design, index optimization, and data migrations |
34
+ | CI/CD & Infrastructure | `devops` | Workflow automation, containerization, and infrastructure scripts |
35
+ | Translations & i18n | `localization` | Multi-language setup, key verification, and cultural audits |
36
+ | System optimization | `performance` | Bundle sizes, latency profiling, and caching strategies |
37
+
28
38
  ## Agent-to-skill baseline
29
39
 
30
40
  | Agent owner | Primary skill set |
package/dist-assets/runbooks/validation-checklist.md CHANGED
@@ -26,16 +26,16 @@ Use this checklist when validating:
26
26
  Primary skill:
27
27
 
28
28
  ```txt
29
- .agents/skills/tester/SKILL.md
29
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
30
30
  ```
31
31
 
32
32
  Supporting skills:
33
33
 
34
34
  ```txt
35
- .agents/skills/build-and-validate/SKILL.md
36
- .agents/skills/pr-orchestrator/SKILL.md
37
- .agents/skills/docs-writer/SKILL.md
38
- .agents/skills/deploy-engineer/SKILL.md
35
+ .ai-workflow/opencode/skills/qa-workflow/SKILL.md
36
+ .ai-workflow/opencode/skills/pr-workflow/SKILL.md
37
+ .ai-workflow/opencode/skills/documentation/SKILL.md
38
+ .ai-workflow/opencode/skills/deployment/SKILL.md
39
39
  ```
40
40
 
41
41
  ## Core validation rule
package/docs/getting-started/authoring-custom-skills.md ADDED
@@ -0,0 +1,80 @@
1
+ # Authoring Custom Skills
2
+
3
+ This guide explains how to author and integrate custom, project-specific capability skills to guide AI agents working inside your repository.
4
+
5
+ ---
6
+
7
+ ## 1. What is a Skill?
8
+
9
+ A **Skill** is a specialized folder containing structured instructions, examples, configurations, and scripts that extend an AI agent's capability for a specific task or technology.
10
+
11
+ By default, the AI Workflow Kit automatically discovers skills placed inside the project configuration directory.
12
+
13
+ ### Recommended Directory Structure
14
+ ```text
15
+ my-custom-skill/
16
+ ├── SKILL.md # Primary instructions (with YAML frontmatter)
17
+ ├── examples/ # Reference implementations and coding patterns (optional)
18
+ ├── scripts/ # Helper validation or build scripts (optional)
19
+ └── references/ # Detailed background specifications and policies (optional)
20
+ ```
21
+
22
+ ---
23
+
24
+ ## 2. The `SKILL.md` Specification
25
+
26
+ The only strictly required file is `SKILL.md`. It must contain a YAML frontmatter section at the very top, containing the skill's name and description.
27
+
28
+ ```markdown
29
+ ---
30
+ name: security-pci-dss
31
+ description: Strict guidelines for PCI-DSS compliance, credit card hashing, and secure payment processing.
32
+ ---
33
+
34
+ # PCI-DSS Secure Coding Skill
35
+
36
+ ## Context
37
+ Use this skill when implementing payment forms, logging mechanisms, or credit card handling modules.
38
+
39
+ ## Non-negotiable Rules
40
+ 1. **Never Log PAN:** The Primary Account Number (PAN) must never be written to application logs, crash reports, or stdout.
41
+ 2. **Use Strong Encryption:** All cardholder data must be encrypted in transit (TLS 1.3) and at rest (AES-256-GCM).
42
+ 3. **No Inline Card Formatting:** Use the custom secure tokenization library. Do not write custom Regex for credit card validation.
43
+ ```
44
+
45
+ ### Frontmatter Fields
46
+ * **`name`**: The unique identifier of the skill. Agents will request this name using the `load_skill` or `load_profile` context directives.
47
+ * **`description`**: A concise, search-friendly summary of the skill's purpose. The classifier uses this description to automatically match the skill to natural language developer requests.
48
+
49
+ ---
50
+
51
+ ## 3. Registering Your Skills
52
+
53
+ The AI Workflow Kit supports two discovery mechanisms:
54
+
55
+ ### Option A: Automatic Discovery (Default)
56
+ Place your skill folder inside the standard project customizations root directory:
57
+ * `.agents/skills/my-custom-skill/`
58
+
59
+ The CLI dynamically loads and indexes all skills in this folder on initialization and execution. No manual registration is required.
60
+
61
+ ### Option B: Shared Customs JSON (`skills.json`)
62
+ If you store your custom skills in a shared or non-standard directory (e.g. to share them across multiple corporate microservices), create a `skills.json` file in your project customizations root:
63
+
64
+ ```json
65
+ {
66
+ "entries": [
67
+ { "path": "node_modules/@corporate/shared-skills/dist" },
68
+ { "path": "infrastructure/shared-skills" }
69
+ ],
70
+ "exclude": ["legacy-v1-tester-skill"]
71
+ }
72
+ ```
73
+
74
+ ---
75
+
76
+ ## 4. Best Practices for Skill Design
77
+
78
+ 1. **Keep Instructions Under 500 Lines:** If your skill requires extensive documentation, store the bulk in the `references/` subdirectory and link to it. Keep the primary `SKILL.md` focused on actionable rules and constraints.
79
+ 2. **Prioritize Capability over Roles:** Name your skills after capabilities (e.g., `performance-tuning`, `database-migrations`) rather than roles (e.g., `tech-lead`, `senior-dev`).
80
+ 3. **Add Validation Scripts:** If a skill enforces a pattern, write a small shell validator script under `scripts/validate.sh` and list it as a requirement in the `validation` section of the functional specifications.
package/docs/getting-started/quickstart.md CHANGED
@@ -44,7 +44,7 @@ This installs the workflow assets into your project:
44
44
  ✔ Created .ai-workflow/
45
45
  ✔ Created opencode.jsonc
46
46
  ✔ Updated .gitignore
47
- ✔ Installed 6 agents, 20 skills, 14 commands, 11 policies
47
+ ✔ Installed 6 agents, 25 skills, 14 commands, 11 policies
48
48
  ```
49
49
 
50
50
  ### Init options
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@williambeto/ai-workflow",
3
- "version": "2.4.8",
3
+ "version": "2.4.9",
4
4
  "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
5
5
  "license": "MIT",
6
6
  "author": "José Willams",
@@ -41,7 +41,6 @@
41
41
  "LICENSE",
42
42
  "CHANGELOG.md",
43
43
  "AGENTS.md",
44
- "read_only_safety_verification.md",
45
44
  "docs/getting-started",
46
45
  "docs/compatibility"
47
46
  ],
package/dist-assets/runbooks/use-linear-for-operational-planning.md DELETED
@@ -1,45 +0,0 @@
1
- # Use an Issue Tracker for Operational Planning
2
-
3
- Use this runbook when a team wants issue-tracker discipline around AI Workflow Kit delivery.
4
-
5
- ## Purpose
6
-
7
- Keep day-to-day execution small, current, and auditable without relying on historical roadmap or backlog documents.
8
-
9
- ## Rule
10
-
11
- The source of truth for active work is the current request, current spec, current plan, current PR breakdown, and current evidence report.
12
-
13
- Historical planning artifacts must not override the current v2 operational contract.
14
-
15
- ## Recommended issue fields
16
-
17
- - Title
18
- - Goal
19
- - Owner
20
- - Execution mode: readonly, quick, standard, full, restricted
21
- - Scope
22
- - Acceptance criteria
23
- - Validation commands
24
- - Evidence link
25
- - Status
26
-
27
- ## Workflow
28
-
29
- 1. Create or update the active spec.
30
- 2. Review scope and readiness.
31
- 3. Create a technical plan.
32
- 4. Break work into small PRs.
33
- 5. Implement with branch recovery.
34
- 6. Document the change.
35
- 7. Add automated tests when viable.
36
- 8. Validate.
37
- 9. Attach evidence.
38
-
39
- ## Done means
40
-
41
- - Scope completed.
42
- - Documentation exists or has a concrete `NOT_APPLICABLE` reason.
43
- - Automated tests pass when viable.
44
- - Validation commands pass.
45
- - Evidence report is complete.
package/dist-assets/runbooks/use-napkin-project-memory.md DELETED
@@ -1,33 +0,0 @@
1
- # Use Project Memory
2
-
3
- This runbook explains how to keep durable project decisions available without creating excessive context noise.
4
-
5
- ## Current name
6
-
7
- Use **Project Memory**. Older names are historical and must not be used in active runtime instructions.
8
-
9
- ## What to store
10
-
11
- Store only durable information:
12
-
13
- - architectural decisions;
14
- - approved workflow contracts;
15
- - package/release constraints;
16
- - known runtime behavior;
17
- - validated project conventions;
18
- - important user decisions.
19
-
20
- Do not store temporary notes, scratch work, obsolete roadmaps, or completed backlog items.
21
-
22
- ## When to update
23
-
24
- Update Project Memory when a task creates or changes a durable decision. Do not update it for ordinary implementation details unless they become project rules.
25
-
26
- ## Evidence
27
-
28
- If Project Memory is updated, include it in the evidence report:
29
-
30
- - what changed;
31
- - why it is durable;
32
- - where it was stored;
33
- - validation performed.
package/read_only_safety_verification.md DELETED
@@ -1,48 +0,0 @@
1
- # Read-Only Safety, Sage Validation, and OpenCode Retest Verification Report
2
-
3
- This report documents the resolution of all blocking items identified to reach the `PASS — publish ready` status.
4
-
5
- ## 1. Summary of Resolved Items
6
-
7
- ### State Machine Transition Correction
8
- - Updated [execute.js](src/commands/execute.js) to transition the state machine sequentially through:
9
- `IMPLEMENTING -> IMPLEMENTED -> VALIDATING -> COMPLETED`
10
- instead of attempting a direct jump from `IMPLEMENTING` to `COMPLETED` during read-only runs.
11
-
12
- ### Snapshot Comparison Bug Fix
13
- - Corrected [compareReadOnlyState](src/commands/execute.js) to compare `.snapshot.files` rather than `.snapshot` directly.
14
- - Standardized comparisons on `.sha256` instead of `.hash`.
15
-
16
- ### Physical File Write Prevention
17
- - Prevented physical file creation of handoff markdown files and execution ledgers inside the repository when running under a read-only request.
18
- - Moved the final ledger logs and handoffs into memory and routed them to `stdout`.
19
- - Declared the block-scoped `plan` variable outside the `try` block so it is properly evaluated in the `finally` block of `runExecute` to suppress file saving.
20
-
21
- ### E2E Test Suite Enhancements
22
- - Added a new E2E test case `16. Read-only válido -> COMPLETED; sem mutações, nenhum handoff ou ledger gravado` inside [consumer-workflow.test.js](tests/e2e/consumer-workflow.test.js) asserting that a valid read-only execution maintains branch, HEAD, and files identically while leaving the `.ai-workflow/` history and handoff directories empty.
23
- - Injected a local controlled OpenCode mock in [verify-packed-consumer.mjs](tests/e2e/verify-packed-consumer.mjs) before running doctor checks, removing dependencies on host/CI global executables.
24
-
25
- ### Integration of Real OpenCode Smoke Test
26
- - Updated `package.json` to link the real OpenCode smoke test (`test:e2e:runtime` with `AI_WORKFLOW_RELEASE=1`) directly into the final `release:verify` command.
27
- - Verified that the smoke test runs and passes successfully on this host environment where the real `opencode` CLI is available.
28
-
29
- ### Sage validation agent for full mode
30
- - Modified [validate](src/core/delegation-controller.js) in the delegation controller to execute validation via the `Sage` agent when the task mode is `"full"`.
31
- - Added unit tests in [delegation-ledger.test.js](tests/unit/delegation-ledger.test.js) to assert that Sage events (`validation_start`, `validation_complete`) are logged.
32
- - Mocked Sage agent capabilities in the E2E framework ([fake-opencode.js](tests/e2e/helpers/fake-opencode.js)) to support a fail-once revalidation scenario.
33
- - Created E2E test case `17. Alto risco / Full -> Astra e Sage executados; com finding, Phoenix e Sage revalidação` to prove the full multi-agent loop:
34
- `Astra -> Sage -> Phoenix -> Sage`
35
-
36
- ---
37
-
38
- ## 2. Verification Evidence
39
-
40
- All consolidated validation checks run and exit with code `0`.
41
-
42
- | Test Run | Command | Result | Details |
43
- | --- | --- | --- | --- |
44
- | **Unit Tests** | `npm run test:unit` | **PASS (142/142)** | All unit tests completed successfully (including the new Sage validation event logging) |
45
- | **E2E Tests** | `npm run test:e2e` | **PASS (18/18)** | All E2E test cases pass successfully, including the new read-only safety validation (16) and multi-agent coordination (17) |
46
- | **All Gates** | `npm run validate` | **PASS (18/18)** | 18 validation checks completed successfully |
47
- | **Packaging** | `npm run pack:verify` | **PASS** | Doctor and Init runs successfully verified against packed tarball |
48
- | **Integrity** | `npm run release:verify` | **PASS (Exit 0)** | Consolidated clean, test, e2e, validate, pack:verify, and real OpenCode smoke tests |