UNPKG

paqad-ai

Version:

Spec-driven development framework — AI agents that think before they type

github.com/Eliyce/paqad-ai

Eliyce/paqad-ai

62 lines (45 loc) • 3.42 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
--- name: documentation-sync-engine description: 'Runs the fast stale-doc detector and dispatches the per-domain doc-sync skills for the affected canonical paths. Use when implementation lands, or just before handoff, on feature-development, bug-fix, refactor or migration work.' metadata: model_tier: medium cacheable: 'false' output_format: markdown paqad-meta: skill.meta.yaml --- ## What It Does Acts as the canonical entry point for post-implementation documentation sync. Runs `diff-doc-sync` first to narrow to actually-stale canonical doc paths, then dispatches each path to the domain-specific maintainer (api, integration, error catalog, canonical, or glossary). Aggregates the results into a single report so the caller does not have to invoke five skills sequentially. The point is to give callers one place to ask "sync the docs after this change" and get consistent, deduplicated output every time. ## Use This When After implementation lands (or just before handoff) on `feature-development`, `bug-fix`, `refactor`, or `migration` workflows. Skip when `differential_refresh` is disabled in the project profile and the team prefers running the per-domain skills directly. ## Inputs - Read the changed file list at `changed_files`. - Use the detector at `detector_script_path` (via `diff-doc-sync`) to produce the stale canonical doc set. - Read `references/orchestration-rules.md` before dispatching so the routing rules and execution order stay consistent across runs. - When `target_domains` is non-empty, intersect the dispatched set with the requested domains. ## Procedure 1. Invoke `diff-doc-sync` with the changed file list to produce the candidate stale doc set (JSON array). 2. Pipe that array's paths into `scripts/route-paths.sh` to assign each path a delegate domain (`api | integration | error | glossary | canonical`); see `assets/routing-table.txt` for the mapping. 3. Apply `target_domains` filtering if provided. 4. Invoke each delegate skill once with only its domain's paths. 5. Aggregate delegate outputs and format per `assets/output.template.md`. 6. Validate with `scripts/lint-output.sh`. ## Output Contract - Return a heading named `Documentation Sync`. - Provide a `Stale Doc Set` line: `Detected: {N} | Routed: {M} | Skipped (target_domains filter): {K}`. - For each domain that ran, emit a third-level heading `### {domain}` and list the paths the delegate updated, plus any consistency warnings the delegate raised. - Provide a `Known Drift` aggregated section pulling from delegates' deferred-drift notes. - When the stale set is empty, return `Documentation Sync: no canonical docs require update.` exactly. See `assets/output.template.md` for the canonical shape; `scripts/lint-output.sh` enforces it. ## Escalate / Stop Conditions - Stop when `diff-doc-sync` cannot run (missing detector, missing changed-files list). - Warn when any delegate reports a consistency warning; surface every such warning in the consolidated report rather than swallowing it. - Do not invent doc paths the detector did not report as stale. - Do not re-route a path between delegates: the per-domain table in `references/orchestration-rules.md` is the only routing source of truth. ## Resources - `references/orchestration-rules.md` - `scripts/route-paths.sh` - `scripts/lint-output.sh` - `assets/output.template.md` - `assets/routing-table.txt` - `agents/openai.yaml`