@open-agent-toolkit/cli 0.3.23 → 0.3.25
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.
- package/assets/bundle-metadata.json +1 -1
- package/assets/docs/docs-tooling/workflows.md +90 -11
- package/assets/docs/reference/cli-reference.md +1 -1
- package/assets/docs/reference/configuration.md +6 -2
- package/assets/public-package-versions.json +4 -4
- package/assets/skills/authoring-docs/SKILL.md +18 -8
- package/assets/skills/authoring-docs/references/guidance-sources.md +95 -0
- package/assets/skills/authoring-docs/references/information-architecture.md +121 -86
- package/assets/skills/authoring-docs/references/page-types.md +35 -7
- package/assets/skills/authoring-docs/references/review-rubric.md +12 -12
- package/assets/skills/authoring-docs/references/templates.md +54 -0
- package/assets/skills/authoring-docs/references/workflow.md +6 -1
- package/assets/skills/authoring-docs/references/writing-style.md +1 -1
- package/assets/skills/authoring-docs/scripts/resolve-guidance.mjs +53 -0
- package/assets/skills/oat-docs-analyze/SKILL.md +140 -7
- package/assets/skills/oat-docs-analyze/references/analysis-artifact-template.md +54 -2
- package/assets/skills/oat-docs-analyze/scripts/package-drift.mjs +129 -0
- package/assets/skills/oat-docs-apply/SKILL.md +148 -11
- package/assets/skills/oat-docs-apply/references/apply-plan-template.md +67 -14
- package/assets/skills/oat-docs-authoring/SKILL.md +20 -8
- package/assets/skills/oat-docs-bootstrap/SKILL.md +74 -15
- package/dist/commands/config/index.d.ts.map +1 -1
- package/dist/commands/config/index.js +118 -1
- package/dist/config/oat-config.d.ts +21 -0
- package/dist/config/oat-config.d.ts.map +1 -1
- package/dist/config/oat-config.js +96 -4
- package/dist/config/resolve.d.ts.map +1 -1
- package/dist/config/resolve.js +5 -1
- package/package.json +2 -2
|
@@ -5,7 +5,7 @@ disable-model-invocation: true
|
|
|
5
5
|
user-invocable: true
|
|
6
6
|
allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Bash(oat:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion
|
|
7
7
|
metadata:
|
|
8
|
-
version: '1.4.
|
|
8
|
+
version: '1.4.6'
|
|
9
9
|
---
|
|
10
10
|
|
|
11
11
|
# Docs Apply
|
|
@@ -33,12 +33,12 @@ Before a parent-branch commit, verify `oat internal commit-paths --help` succeed
|
|
|
33
33
|
|
|
34
34
|
- No unapproved documentation changes.
|
|
35
35
|
- No branch creation before the recommendation plan is reviewed.
|
|
36
|
-
- No changes outside the documentation scope except
|
|
36
|
+
- No changes outside the documentation scope except the approved IA record/config mirrors, owner-authorized nav sync, tracking updates, and the individually approved tooling-update carve-out below.
|
|
37
37
|
|
|
38
38
|
**ALLOWED Activities:**
|
|
39
39
|
|
|
40
40
|
- Reading analysis artifacts and the current docs surface.
|
|
41
|
-
- Creating or updating docs files and
|
|
41
|
+
- Creating or updating docs files and hand-authored navigation when approved. Nav-sync-owned navigation changes only through `oat docs nav sync`; undeclared ownership blocks regeneration.
|
|
42
42
|
- Running `oat docs nav sync` after approved structural changes.
|
|
43
43
|
- Creating branches, commits, and optional PRs.
|
|
44
44
|
|
|
@@ -93,7 +93,13 @@ When executing this skill, provide lightweight progress feedback so the user can
|
|
|
93
93
|
|
|
94
94
|
### Step 0: Intake - Find Analysis Artifact
|
|
95
95
|
|
|
96
|
-
|
|
96
|
+
The one input is an **analysis artifact path plus approved recommendation IDs**.
|
|
97
|
+
Accept an explicitly supplied artifact; when none is supplied, offer the newest
|
|
98
|
+
artifact below and confirm that it is the reviewed input. Never silently switch
|
|
99
|
+
to a newer artifact after approval. IDs identify recommendations within that
|
|
100
|
+
artifact, remain stable through artifact review, and are never reassigned.
|
|
101
|
+
|
|
102
|
+
Locate a candidate when no artifact path was supplied:
|
|
97
103
|
|
|
98
104
|
```bash
|
|
99
105
|
ls -t .oat/repo/analysis/docs-*.md 2>/dev/null | head -1
|
|
@@ -103,6 +109,8 @@ If none exists, stop and instruct the user to run `oat-docs-analyze`.
|
|
|
103
109
|
|
|
104
110
|
Validate that each recommendation in the artifact includes:
|
|
105
111
|
|
|
112
|
+
- a unique stable ID (for example `R-001`)
|
|
113
|
+
- `approval: explicit | default`
|
|
106
114
|
- evidence
|
|
107
115
|
- confidence
|
|
108
116
|
- disclosure
|
|
@@ -158,9 +166,19 @@ For review-mode and follow-up decisions, use host-aware prompting:
|
|
|
158
166
|
|
|
159
167
|
If the user chooses `apply all`:
|
|
160
168
|
|
|
161
|
-
- confirm the full plan
|
|
162
|
-
-
|
|
163
|
-
-
|
|
169
|
+
- confirm the full plan and capture global notes
|
|
170
|
+
- approve only non-blocked `approval: default` recommendations, excluding named exceptions
|
|
171
|
+
- Blanket approval never approves an `approval: explicit` recommendation.
|
|
172
|
+
- Ask for individual approval by recommendation ID for each explicit item. A
|
|
173
|
+
restructure block always needs its own approval, including its full map and
|
|
174
|
+
old-URL plan; approving a different block does not approve it.
|
|
175
|
+
|
|
176
|
+
In unattended mode, skip every explicit recommendation even when an input list
|
|
177
|
+
names its ID; report `explicit_requires_interactive_approval` in the structured
|
|
178
|
+
result. Never interpret automation configuration or `apply all` as individual
|
|
179
|
+
approval. Missing/unknown approval classes or duplicate/unknown IDs block intake.
|
|
180
|
+
The approved-ID list is captured at this approval step, not inferred from prose.
|
|
181
|
+
An input list alone does not prove individual approval for an explicit item.
|
|
164
182
|
|
|
165
183
|
If the user chooses `apply interactively`, ask for each recommendation:
|
|
166
184
|
|
|
@@ -174,11 +192,12 @@ If the user chooses `discuss`, answer questions, revise the plan if needed, and
|
|
|
174
192
|
- `apply interactively`
|
|
175
193
|
- `discuss`
|
|
176
194
|
|
|
177
|
-
If all recommendations are skipped, stop without changing files.
|
|
195
|
+
If all recommendations are skipped, emit the structured result with reasons and stop without changing files.
|
|
178
196
|
|
|
179
197
|
Build an `APPLIED_PLAN_DETAILS` block from approved or modified recommendations with:
|
|
180
198
|
|
|
181
199
|
- recommendation id
|
|
200
|
+
- approval class and individual approval evidence when required
|
|
182
201
|
- action
|
|
183
202
|
- target path
|
|
184
203
|
- disclosure
|
|
@@ -200,6 +219,24 @@ If branch creation fails because of unrelated local changes, ask the user to res
|
|
|
200
219
|
|
|
201
220
|
### Step 4: Apply Approved Changes
|
|
202
221
|
|
|
222
|
+
Independently probe each exact `authoring-docs/SKILL.md` in order:
|
|
223
|
+
`${SKILL_DIR}/..` from the loaded skill (`SKILL_DIR` is the absolute directory
|
|
224
|
+
containing that loaded `SKILL.md`), `${HOME}/.agents/skills`, then
|
|
225
|
+
`<repo-root>/.agents/skills`. Bind the first matching `authoring-docs` directory
|
|
226
|
+
once as `AUTHORING_DOCS_ROOT`; load `${AUTHORING_DOCS_ROOT}/SKILL.md` and use
|
|
227
|
+
that same root for every authoring-docs reference and script, never ambient
|
|
228
|
+
discovery. If none is found, name `authoring-docs`, stop this handoff, and give
|
|
229
|
+
the intended-scope recovery command: `oat tools install docs --scope <user|project>`
|
|
230
|
+
or `oat tools update --pack docs --scope <user|project>`.
|
|
231
|
+
|
|
232
|
+
Before content actions, use its page-purpose, landing, placement and five-axis IA
|
|
233
|
+
method within the approved recommendation scope. Carry the analysis artifact's ordered guidance
|
|
234
|
+
locators/provenance into the apply plan; do not silently re-resolve different
|
|
235
|
+
sources. Verify cited inputs still exist and remain read-only outside the repo.
|
|
236
|
+
Local AGENTS/contributing rules stay authoritative; a conflict is `ask_user`
|
|
237
|
+
and blocks that recommendation pending a fresh analysis/user decision. Cite
|
|
238
|
+
sources without copying private contents.
|
|
239
|
+
|
|
203
240
|
Before the first approved write, initialize `OWNED_OUTPUT_FILES=()`. Append
|
|
204
241
|
each exact successfully created, modified or removed path at that write,
|
|
205
242
|
including both names of a rename and any generated navigation/index file this
|
|
@@ -217,10 +254,87 @@ For each approved recommendation:
|
|
|
217
254
|
- `omit` -> do not encode the item in the docs change
|
|
218
255
|
- `ask_user` -> require explicit user confirmation before writing
|
|
219
256
|
|
|
257
|
+
#### Record an accepted IA
|
|
258
|
+
|
|
259
|
+
Only an approved `record-ia` recommendation authorizes persistence. Before any
|
|
260
|
+
PJM/decision write run `oat pjm doctor --json` in the target repo and inspect
|
|
261
|
+
`adoption.state`; absent/partial adoption routes to `oat pjm init` before the
|
|
262
|
+
record, never silently writes an unmanaged decision. Read the target's
|
|
263
|
+
`.oat/repo/AGENTS.md`, decision conventions and existing decision index; update
|
|
264
|
+
an existing matching record rather than duplicate it. Create a new record with
|
|
265
|
+
`oat decision new "Documentation information architecture" --status accepted
|
|
266
|
+
--context "<approved evidence>"` and its supported `--decision`/`--consequences` options
|
|
267
|
+
(check `--help`). The command owns index generation; never hand-edit the index.
|
|
268
|
+
|
|
269
|
+
Write a short `## Information architecture` section with tracks, organizing
|
|
270
|
+
principle per track, placement rules and verification overlay. For Fumadocs and
|
|
271
|
+
MkDocs put it in the docs-app `AGENTS.md`, preserving existing guidance. For
|
|
272
|
+
Markdown put it in the contributing page; create no docs-root `AGENTS.md`.
|
|
273
|
+
Link the decision and authored section reciprocally. They remain authoritative;
|
|
274
|
+
a conflict with config becomes `ask_user`, never a config-driven rewrite.
|
|
275
|
+
|
|
276
|
+
Mirror the accepted record using shared repo config only:
|
|
277
|
+
`oat config set documentation.ia '<JSON>'`, with exactly `{preset, decision,
|
|
278
|
+
tracks?: [{path, principle}], verification?: 'triad'|'agent-only'|'none'}`.
|
|
279
|
+
`decision` is repo-relative; preserve guidance and unrelated config. For a
|
|
280
|
+
framework surface, separately record the operator's approved sidebar owner via
|
|
281
|
+
`oat config set documentation.navOwner nav-sync` or `hand-authored`. Missing
|
|
282
|
+
ownership stays undeclared and blocks automatic regeneration. Markdown ignores
|
|
283
|
+
navOwner and never runs nav sync. New-scaffold default ownership and preset
|
|
284
|
+
materialization are not implemented by this persistence step.
|
|
285
|
+
|
|
286
|
+
#### Restructure one approved block
|
|
287
|
+
|
|
288
|
+
`restructure` requires `approval: explicit` and one individual approval per
|
|
289
|
+
block before any move. Use the apply-plan block: source→destination map, source
|
|
290
|
+
and destination parent Contents edits, grep-derived inbound references (including
|
|
291
|
+
relative links, anchors and assets), exact rewrite list, and old-URL recovery.
|
|
292
|
+
Search the whole repo for each old path/basename with `rg`; resolve relative
|
|
293
|
+
references from their original file and check them again from their new location.
|
|
294
|
+
Keep links to moved headings working. Do not treat search hits in examples or
|
|
295
|
+
unrelated same-name files as automatic rewrites.
|
|
296
|
+
|
|
297
|
+
Choose recovery supported by the actual deployment: Next static export does
|
|
298
|
+
not support Next config redirects (see [Next static-export unsupported features](https://nextjs.org/docs/app/guides/static-exports#unsupported-features)).
|
|
299
|
+
Use an authored stub at the old route with a relative pointer, or an approved
|
|
300
|
+
archive pointer; a redirect requires verified framework/host support and stays
|
|
301
|
+
manual when it needs app/host config. Never edit `not-found.tsx` through this
|
|
302
|
+
carve-out. Retired pages retain a stub/archive pointer and a parent Contents
|
|
303
|
+
update, never a silent delete. Preserve stub routes in the approved reader map
|
|
304
|
+
where the framework needs them to build.
|
|
305
|
+
|
|
306
|
+
Apply one block as one exact-path implementation commit; do not combine it with
|
|
307
|
+
another block. Validate all rewritten inbound links and old URLs under the
|
|
308
|
+
actual base path. With `navOwner: nav-sync`, run nav sync then nav sync --check
|
|
309
|
+
with the explicit app target. With `hand-authored`, update approved hand-authored
|
|
310
|
+
navigation and compare membership/order against Contents read-only; never run a
|
|
311
|
+
writing nav sync. With undeclared ownership, report `ask_user` before navigation
|
|
312
|
+
writes. Markdown checks files/Contents/links only. Re-run `oat-docs-analyze`
|
|
313
|
+
after each block, preserving residual findings instead of claiming a clean run.
|
|
314
|
+
|
|
315
|
+
#### Individually approved tooling update
|
|
316
|
+
|
|
317
|
+
A `tooling-update` recommendation has `approval: explicit`. Even with individual
|
|
318
|
+
approval, its out-of-Markdown allowance is only these three operations:
|
|
319
|
+
|
|
320
|
+
1. Bump the docs app's existing `@open-agent-toolkit/docs-*` dependencies to the
|
|
321
|
+
bundled versions using the artifact's exact upgrade command (preserve dependency
|
|
322
|
+
section and package manager; include its resulting lockfile only). Never downgrade
|
|
323
|
+
an installed version: `ahead` or `unverified` requires CLI selection/update or
|
|
324
|
+
manual verification before re-analysis, not a docs-package tooling update.
|
|
325
|
+
2. Run `oat docs migrate --docs-dir <authored-root> --apply` only for its currently
|
|
326
|
+
supported admonition conversions and injected frontmatter; inspect the diff.
|
|
327
|
+
3. Run the docs build verifier from the app's existing scripts.
|
|
328
|
+
|
|
329
|
+
Scaffold changes the CLI cannot make (app config, routes, package scripts) are
|
|
330
|
+
`manual`: report the required change and ID without editing those files. This
|
|
331
|
+
allowance does not permit application dependencies, host settings, arbitrary
|
|
332
|
+
migrations or an app-shell rebuild. Other out-of-scope prohibitions remain.
|
|
333
|
+
|
|
220
334
|
When approved actions involve docs app creation or nav updates:
|
|
221
335
|
|
|
222
336
|
- Use `oat docs init` for scaffolding when appropriate.
|
|
223
|
-
- Use `oat docs nav sync` instead of manually editing nav when
|
|
337
|
+
- Use `oat docs nav sync` instead of manually editing nav only when recorded `navOwner: nav-sync` authorizes it. In Fumadocs apps it writes strict `meta.json` files and reports pages no `## Contents` map lists (`unlisted` in `--json`); resolve a reported page through an approved `## Contents` change, never by hand-editing `meta.json`.
|
|
224
338
|
|
|
225
339
|
Negative rules:
|
|
226
340
|
|
|
@@ -243,7 +357,7 @@ full configured content tree; keep the authored config index unchanged.
|
|
|
243
357
|
For framework apps, discover actual scripts and run the smallest relevant
|
|
244
358
|
verification set based on what changed; these examples apply only when present:
|
|
245
359
|
|
|
246
|
-
- `oat docs nav sync`
|
|
360
|
+
- `oat docs nav sync --target-dir <docs-app>` then `--check` only for `nav-sync` ownership; hand-authored/undeclared navigation gets read-only Contents membership/order comparison
|
|
247
361
|
- `pnpm --dir <docs-app> docs:lint` (no-op when no linter is configured)
|
|
248
362
|
- `pnpm --dir <docs-app> docs:format:check`
|
|
249
363
|
- `pnpm --dir <docs-app> docs:build`
|
|
@@ -252,7 +366,7 @@ If no docs app exists yet, use file-level verification and confirm the structura
|
|
|
252
366
|
|
|
253
367
|
### Step 6: Commit and PR
|
|
254
368
|
|
|
255
|
-
Commit the approved changes:
|
|
369
|
+
Commit the approved changes (for restructure, repeat with one retained identity and exact path list per approved block; exclude already committed blocks from any final aggregate commit and skip an empty aggregate):
|
|
256
370
|
|
|
257
371
|
```bash
|
|
258
372
|
OWNED_COMMIT_PATHS=("${OWNED_OUTPUT_FILES[@]}")
|
|
@@ -326,6 +440,29 @@ PR creation failed. To create manually:
|
|
|
326
440
|
|
|
327
441
|
### Step 7: Update Tracking and Output Summary
|
|
328
442
|
|
|
443
|
+
Always emit this structured result, including no-op/unattended runs. Each input
|
|
444
|
+
recommendation ID appears in exactly one outcome; failed verification is a
|
|
445
|
+
failure, never an applied success. Unsupported scaffold work is skipped with
|
|
446
|
+
reason `manual` and its required change. Include individual approval evidence
|
|
447
|
+
in the plan, not invented in this result.
|
|
448
|
+
|
|
449
|
+
```json
|
|
450
|
+
{
|
|
451
|
+
"analysisArtifact": ".oat/repo/analysis/docs-example.md",
|
|
452
|
+
"approvedRecommendationIds": ["R-001"],
|
|
453
|
+
"applied": ["R-001"],
|
|
454
|
+
"skipped": [
|
|
455
|
+
{ "id": "R-002", "reason": "explicit_requires_interactive_approval" }
|
|
456
|
+
],
|
|
457
|
+
"failed": []
|
|
458
|
+
}
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
Failed entries use `{ "id": "R-003", "reason": "<verification/error>" }`.
|
|
462
|
+
Report partial writes and stop on a failure; never continue by widening scope.
|
|
463
|
+
|
|
464
|
+
### Tracking and summary
|
|
465
|
+
|
|
329
466
|
Update shared tracking:
|
|
330
467
|
|
|
331
468
|
```bash
|
|
@@ -12,11 +12,20 @@ oat_docs_target: { docs-target-path }
|
|
|
12
12
|
**Source Analysis:** `{analysis-artifact-path}`
|
|
13
13
|
**Docs Target:** `{docs-target-path}`
|
|
14
14
|
|
|
15
|
+
## Guidance provenance
|
|
16
|
+
|
|
17
|
+
- Analysis-selected IA sources, in order: {locators + provenance}
|
|
18
|
+
- Local authority: {AGENTS/contributing citations}
|
|
19
|
+
- Read-only sources verified: {resolved entries or blocked recommendation IDs}
|
|
20
|
+
- Conflicts: {ask_user disposition or none}
|
|
21
|
+
|
|
22
|
+
Keep the analysis selection; do not copy private contents or invent missing evidence.
|
|
23
|
+
|
|
15
24
|
## Instructions
|
|
16
25
|
|
|
17
26
|
Review the full recommendation set first, then choose a review mode:
|
|
18
27
|
|
|
19
|
-
- **apply all** — approve
|
|
28
|
+
- **apply all** — approve non-blocked default items; explicit items require individual approval by ID
|
|
20
29
|
- **apply interactively** — review recommendation by recommendation
|
|
21
30
|
- **discuss** — pause to talk through the plan before approving
|
|
22
31
|
|
|
@@ -32,19 +41,21 @@ blocked pending a fresh analysis rather than guessed.
|
|
|
32
41
|
|
|
33
42
|
## Recommendations
|
|
34
43
|
|
|
35
|
-
### {
|
|
36
|
-
|
|
37
|
-
| Field | Value
|
|
38
|
-
| ------------ |
|
|
39
|
-
|
|
|
40
|
-
|
|
|
41
|
-
|
|
|
42
|
-
|
|
|
43
|
-
|
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
44
|
+
### {R-NNN}. {Action}: `{target-path}`
|
|
45
|
+
|
|
46
|
+
| Field | Value |
|
|
47
|
+
| ------------ | -------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| ID | {R-NNN; stable within the source artifact} |
|
|
49
|
+
| approval | {explicit / default; never inferred from blanket consent} |
|
|
50
|
+
| Action | {create / update / move / scaffold / sync-nav / record-ia / restructure / tooling-update / manual} |
|
|
51
|
+
| Target | `{target-path}` |
|
|
52
|
+
| Rationale | {why this recommendation exists} |
|
|
53
|
+
| Source | {finding # / contract gap / nav issue} |
|
|
54
|
+
| Evidence | {exact file refs / config / docs that justify the recommendation} |
|
|
55
|
+
| Confidence | {high / medium / low} |
|
|
56
|
+
| Disclosure | {inline / link_only / omit / ask_user} |
|
|
57
|
+
| Link Targets | {path or URL when link_only; otherwise N/A} |
|
|
58
|
+
| Helper | `oat docs nav sync` / `oat docs init` / `manual edit` |
|
|
48
59
|
|
|
49
60
|
**Context:** {1-2 sentences}
|
|
50
61
|
|
|
@@ -55,6 +66,29 @@ blocked pending a fresh analysis rather than guessed.
|
|
|
55
66
|
|
|
56
67
|
{Repeat for each recommendation}
|
|
57
68
|
|
|
69
|
+
## Restructure block (one individually approved ID, one exact-path commit)
|
|
70
|
+
|
|
71
|
+
- ID / individual approval evidence: {R-NNN / operator choice, or pending}
|
|
72
|
+
- Source → destination map: {every moved/retired page}
|
|
73
|
+
- Parent Contents edits: {source and destination indexes}
|
|
74
|
+
- Grep-derived inbound rewrites: {command + referring file:line + old/new link,
|
|
75
|
+
including anchors/assets and rewritten links inside moved pages}
|
|
76
|
+
- Old-URL strategy: {verified host redirect, authored stub, or archive pointer;
|
|
77
|
+
static export: no assumed Next redirects}
|
|
78
|
+
- Retired-page recovery: {retained stub/archive pointer + parent Contents entry}
|
|
79
|
+
- Sidebar owner: {nav-sync / hand-authored / undeclared; Markdown: ignored}
|
|
80
|
+
- Verification: {nav-sync write then --check, or read-only membership/order
|
|
81
|
+
comparison; file/link checks; actual base-path old URL; analyze rerun}
|
|
82
|
+
- Exact owned files and commit identity: {list including both rename sides}
|
|
83
|
+
|
|
84
|
+
## IA recording / tooling limits
|
|
85
|
+
|
|
86
|
+
- Record IA: {adoption.state from target pjm doctor; decision command/path;
|
|
87
|
+
framework AGENTS or Markdown contributing section; shared mirror JSON}
|
|
88
|
+
- Tooling update: {individually approved ID; exact docs-app docs-\* upgrade
|
|
89
|
+
command; supported migrate conversions; existing build verifier}
|
|
90
|
+
- Unsupported app config/routes/scripts: {manual required changes; no edits}
|
|
91
|
+
|
|
58
92
|
## Summary of Actions
|
|
59
93
|
|
|
60
94
|
| # | Action | Target | Disclosure | Decision |
|
|
@@ -64,6 +98,25 @@ blocked pending a fresh analysis rather than guessed.
|
|
|
64
98
|
|
|
65
99
|
**Total:** {N} approved, {N} modified, {N} skipped
|
|
66
100
|
|
|
101
|
+
## Structured result
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"analysisArtifact": "{path}",
|
|
106
|
+
"approvedRecommendationIds": ["R-001"],
|
|
107
|
+
"applied": ["R-001"],
|
|
108
|
+
"skipped": [
|
|
109
|
+
{ "id": "R-002", "reason": "explicit_requires_interactive_approval" }
|
|
110
|
+
],
|
|
111
|
+
"failed": []
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Every input ID has exactly one outcome. Unattended explicit items are skipped
|
|
116
|
+
regardless of the supplied ID list. Missing/unknown class or ID blocks intake.
|
|
117
|
+
Use reason `manual` with the required change for unsupported scaffold work;
|
|
118
|
+
failed entries carry an ID and error/verification reason.
|
|
119
|
+
|
|
67
120
|
## Proceed?
|
|
68
121
|
|
|
69
122
|
Confirm to begin applying the approved documentation changes.
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: oat-docs-authoring
|
|
3
3
|
description: Use when authoring or restructuring targeted content inside an existing OAT Markdown surface or OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.
|
|
4
|
-
argument-hint: '[docs task or target path]'
|
|
4
|
+
argument-hint: '[docs task or target path] [--ia-guidance <path|url>]'
|
|
5
5
|
disable-model-invocation: false
|
|
6
6
|
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
|
7
7
|
user-invocable: true
|
|
8
8
|
metadata:
|
|
9
|
-
version: '1.
|
|
9
|
+
version: '1.2.0'
|
|
10
10
|
---
|
|
11
11
|
|
|
12
12
|
# OAT Docs Authoring
|
|
@@ -14,9 +14,8 @@ metadata:
|
|
|
14
14
|
Use this skill for targeted documentation authoring and small structural edits
|
|
15
15
|
inside an existing OAT Markdown surface or OAT/Fumadocs docs app.
|
|
16
16
|
|
|
17
|
-
This is a thin wrapper over `authoring-docs
|
|
18
|
-
|
|
19
|
-
and review standards. Keep this wrapper focused on OAT Markdown/Fumadocs placement,
|
|
17
|
+
This is a thin wrapper over `authoring-docs` for universal evidence gathering,
|
|
18
|
+
page-type selection, writing style, templates, and review standards. Keep this wrapper focused on OAT Markdown/Fumadocs placement,
|
|
20
19
|
navigation, generated artifacts, validation, and lifecycle boundaries.
|
|
21
20
|
|
|
22
21
|
## Prerequisites
|
|
@@ -111,9 +110,22 @@ Use `references/docs-root-resolution.md` before assuming any path. OAT docs apps
|
|
|
111
110
|
commonly live outside `apps/oat-docs`, and `.oat/config.json` may describe the
|
|
112
111
|
generated root index separately from the authored docs root.
|
|
113
112
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
113
|
+
Independently probe each exact `authoring-docs/SKILL.md` in order:
|
|
114
|
+
`${SKILL_DIR}/..` from the loaded skill (`SKILL_DIR` is the absolute directory
|
|
115
|
+
containing that loaded `SKILL.md`), `${HOME}/.agents/skills`, then
|
|
116
|
+
`<repo-root>/.agents/skills`. Bind the first matching `authoring-docs` directory
|
|
117
|
+
once as `AUTHORING_DOCS_ROOT`; load `${AUTHORING_DOCS_ROOT}/SKILL.md` and use
|
|
118
|
+
that same root for every authoring-docs reference and script, never ambient
|
|
119
|
+
discovery. If none is found, name `authoring-docs`, stop this handoff, and give
|
|
120
|
+
the intended-scope recovery command: `oat tools install docs --scope <user|project>`
|
|
121
|
+
or `oat tools update --pack docs --scope <user|project>`.
|
|
122
|
+
|
|
123
|
+
Use the bound skill's reference map for evidence gathering, page type, writing
|
|
124
|
+
style, templates and review rubric. For IA work use its five-axis method and
|
|
125
|
+
`${AUTHORING_DOCS_ROOT}/references/guidance-sources.md`: explicit `--ia-guidance` or
|
|
126
|
+
conversation → repo config → user config → built-in. Cite ordered source
|
|
127
|
+
locators/provenance in the handoff; respect AGENTS/contributing authority,
|
|
128
|
+
keep non-repo sources read-only and report conflicts as `ask_user`.
|
|
117
129
|
|
|
118
130
|
### Step 2: Inspect Evidence and Local Maps
|
|
119
131
|
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: oat-docs-bootstrap
|
|
3
3
|
description: Use when bootstrapping or adopting an OAT documentation surface in a repo. Guides the user through preflight detection, richer input gathering than the raw CLI, `oat docs init` invocation with gated post-patches for open CLI gaps, build verification, post-scaffold config inspection, and an educational walkthrough. Supports plain Markdown (file-level path), Fumadocs (full path), and MkDocs (lean path with defined minimum contract).
|
|
4
|
-
argument-hint: '<optional-target-dir>'
|
|
4
|
+
argument-hint: '<optional-target-dir> [--ia-guidance <path|url>]'
|
|
5
5
|
disable-model-invocation: true
|
|
6
6
|
user-invocable: true
|
|
7
7
|
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
|
8
8
|
metadata:
|
|
9
|
-
version: '1.
|
|
9
|
+
version: '1.4.1'
|
|
10
10
|
---
|
|
11
11
|
|
|
12
12
|
# Docs Bootstrap
|
|
@@ -114,13 +114,15 @@ OAT ▸ DOCS BOOTSTRAP
|
|
|
114
114
|
|
|
115
115
|
The detailed framework procedures below apply to Fumadocs/MkDocs. When the selected tooling is `markdown`, use this path for Steps 2–7 instead; never run framework post-patches, the FP-15 AGENTS bridge, dependency discovery/install, package/Turbo patches, or a site build. Step 1 remains the shared read-only detector.
|
|
116
116
|
|
|
117
|
-
1. **Preflight and routing:** Read `documentation.tooling` as a non-empty string. A non-string value (including a legacy object with a `framework` field) is invalid/undeclared tooling in the CLI; surface it for a user decision before proceeding, without silently clearing or retagging it. Declared tooling is authoritative: configured Markdown uses `documentation.root` literally, including when it contains a child named `docs`; declared frameworks or unknown stacks are not plain-doc adoption candidates. With no declared tooling, check framework evidence first (`mkdocs.yml`, Fumadocs/Next config and docs-app package scripts/dependencies), then inspect the chosen dedicated content directory for authored `.md`/`.mdx` pages. A repository-root README alone is insufficient; an empty selected directory is fresh setup. For a populated plain tree,
|
|
117
|
+
1. **Preflight and routing:** Read `documentation.tooling` as a non-empty string. A non-string value (including a legacy object with a `framework` field) is invalid/undeclared tooling in the CLI; surface it for a user decision before proceeding, without silently clearing or retagging it. Declared tooling is authoritative: configured Markdown uses `documentation.root` literally, including when it contains a child named `docs`; declared frameworks or unknown stacks are not plain-doc adoption candidates. With no declared tooling, check framework evidence first (`mkdocs.yml`, Fumadocs/Next config and docs-app package scripts/dependencies), then inspect the chosen dedicated content directory for authored `.md`/`.mdx` pages. A repository-root README alone is insufficient; an empty selected directory is fresh setup. For a populated plain tree, default to `oat-docs-analyze` then `oat-docs-apply` for approved repairs and exit without scaffolding. Offer **adopt and audit**, **audit only**, or **abort** when adoption is explicitly requested. Audit only delegates read-only to `oat-docs-analyze` and exits. Adoption requires the explicit user choice and CLI `--adopt`; `--yes` alone never authorizes it. An incompatible declared root/index/tooling requires a user decision, with no silent clearing or retagging. Keep the existing explicitly authorized framework replacement path when a framework is selected.
|
|
118
118
|
2. **Gather inputs:** Offer “Markdown (plain files), Fumadocs, or MkDocs?” Collect documentation title (`--site-name`), dedicated relative target directory (default `docs` in every repo shape), and optional description. Reuse an existing compatible configured Markdown root. Ask no app/package name, package-manager, site-runtime, or dependency questions. Lint and format default to `none`; describe selected existing repository tools only, without installing them. Validate a nonempty title and a dedicated in-repository target, excluding the repository root and escaping symlinks. Confirm fresh setup or additive adoption, title, root, and audit handoff. `appName` is absent and `conflictResolution` is `adopt`, `audit`, `abort`, or null for this path.
|
|
119
|
+
Before Markdown CLI invocation, run **Step 2.5** for fresh setup and explicitly selected adoption; it is not bypassed by this condensed path.
|
|
120
|
+
|
|
119
121
|
3. **Invoke CLI:** Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without post-patches. For success, read config back to resolve the actual content root and authored index.
|
|
120
122
|
4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Fresh setup creates only authored `index.md` and `contributing.md` in the target; verify no docs-root AGENTS, app package, framework config, dependencies, or root build changes. Run already documented lint/link/format checks when applicable; otherwise inspect files/links directly. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
|
|
121
123
|
5. **Inspect config:** `documentation.tooling` is the string `markdown`; `root` is the literal content directory; `index` is its authored entrypoint, normally `<root>/index.md`. Markdown introduces no `documentation.config`. Preserve unrelated config/excludes/completion settings. Verify deterministic managed root Documentation guidance names that root, Markdown tooling, authored index, and `<root>/contributing.md`; preserve manual/local guidance and surface unresolved disposition. The Step 5e completion opt-in remains available using the docs root rather than an app name, without silently changing an existing value. No nested app-config reconciliation or framework patch inspection applies.
|
|
122
124
|
6. **Walkthrough:** In short chunks, show actual config and `<root>/index.md`: useful context plus the Contents map, title/description metadata, sibling `page.md` and child `section/index.md` links, exclusions and asset-only exceptions. Explain adding a page/section and updating the nearest authored map without overwriting existing context. Root AGENTS Documentation guidance and `<root>/contributing.md` establish agent/human conventions; a preexisting local AGENTS file remains authoritative, but bootstrap creates none. Authored indexes are edited directly. Optional generated inventories require explicit external output, e.g. `$CLI_CMD docs generate-index --docs-dir <root> --output .oat/docs-manifest.md`; output must stay outside the full configured content root and cannot overwrite the configured authored index even with a narrowed `--docs-dir`. Generation does not repoint `documentation.index`. Markdown bootstrap never generates a manifest automatically. Skip framework deep dives and preview-server/build commands.
|
|
123
|
-
7. **Audit handoff and summary:** Offer `oat-docs-analyze` against the literal configured root, followed by `oat-docs-apply` only for approved repairs. An adopted incomplete tree needs that audit; config/guidance alone prove no full conformance. Explain `oat-project-document` for source-backed project deltas. Summarize tooling, actual root/authored index, created/preserved files, guidance/config disposition, file-check outcomes, unresolved audit gaps, optional manifest ownership, and exact skill handoff. For dry-run/partial/refusal, label the outcome accordingly rather than printing BOOTSTRAP COMPLETE. No app, install, build, patch, or dev-command fields apply.
|
|
125
|
+
7. **Audit handoff and summary:** Offer `oat-docs-analyze` against the literal configured root, followed by `oat-docs-apply` only for approved repairs. An adopted incomplete tree needs that audit; config/guidance alone prove no full conformance. Explain `oat-project-document` for source-backed project deltas. Summarize tooling, actual root/authored index, created/preserved files, guidance/config disposition, ordered IA guidance locators/provenance and proposal recommendation/conflicts, file-check outcomes, unresolved audit gaps, optional manifest ownership, and exact skill handoff. For dry-run/partial/refusal, label the outcome accordingly rather than printing BOOTSTRAP COMPLETE. No app, install, build, patch, or dev-command fields apply.
|
|
124
126
|
|
|
125
127
|
### Step 1: Preflight Detector
|
|
126
128
|
|
|
@@ -155,7 +157,7 @@ Read (do not modify):
|
|
|
155
157
|
|
|
156
158
|
Build `conflicts: []` by adding an entry for each finding:
|
|
157
159
|
|
|
158
|
-
- If `configDocumentation`
|
|
160
|
+
- If `configDocumentation` declares a docs surface (`root`, `tooling`, `index` or `config`) → `{ kind: 'existing-config', detail: <summary of what's there> }`. A guidance-only section is an IA input, not evidence of an existing docs surface; retain it and continue fresh setup.
|
|
159
161
|
- If `docsAppPath` exists on disk → `{ kind: 'existing-app-dir', detail: <path + whether it has uncommitted changes> }`
|
|
160
162
|
- If `agentsMdSection` is true → `{ kind: 'existing-agents-section', detail: <what the section says> }`
|
|
161
163
|
|
|
@@ -208,7 +210,7 @@ Print `[2/7] Gathering inputs…` at the start of this step.
|
|
|
208
210
|
|
|
209
211
|
**2a. Resolve Preflight conflicts (if any).**
|
|
210
212
|
|
|
211
|
-
If `conflicts[]` from Preflight is non-empty, present them together and
|
|
213
|
+
If `conflicts[]` from Preflight is non-empty, present them together and default to `repair`: run `oat-docs-analyze` (with `--ia` when structure is requested), review its artifact, then `oat-docs-apply` for approved repairs and exit. Use replacement or a second app only after an explicit user choice; a generic request to bootstrap is insufficient. See the **Conflict Resolution Contract** below. Do not scaffold until that contract is satisfied.
|
|
212
214
|
|
|
213
215
|
If `conflicts[]` is empty, skip conflict handling and go to 2b.
|
|
214
216
|
|
|
@@ -271,14 +273,14 @@ Input Result:
|
|
|
271
273
|
|
|
272
274
|
#### Conflict Resolution Contract (sub-procedure)
|
|
273
275
|
|
|
274
|
-
When Preflight (Step 1) records non-empty `conflicts[]`, present them to the user
|
|
276
|
+
When Preflight (Step 1) records non-empty `conflicts[]`, present them together and default to `repair` unless the user explicitly selects another resolution. Record exactly one resolution. Each resolution below has a precise definition in terms of **allowed mutations**, **preserved state**, and **stop conditions**. The Scaffold Runner (Step 3) reads the chosen resolution and adjusts its behavior; it never reinvents these semantics.
|
|
275
277
|
|
|
276
278
|
Resolution options:
|
|
277
279
|
|
|
278
280
|
- **`replace`** — Treat the existing docs setup as disposable and scaffold fresh.
|
|
279
281
|
- **Allowed mutations (executed by this sub-procedure before Scaffold Runner begins):**
|
|
280
282
|
- Remove the existing docs app directory (`existingDocs.docsAppPath`), if present on disk.
|
|
281
|
-
-
|
|
283
|
+
- Clear the replaced surface fields in `documentation` in `$REPO_ROOT/.oat/config.json`, preserving `documentation.guidance` if present. The CLI will rewrite surface ownership during init; advisory guidance is unrelated to the discarded scaffold.
|
|
282
284
|
- Remove the `## Documentation` section from `$REPO_ROOT/AGENTS.md`, if present. The CLI upserts its own.
|
|
283
285
|
- **Preserved state:** Everything outside the three touchpoints above. Git history is preserved — deletions are tracked normally and remain recoverable via `git revert` / `git checkout`.
|
|
284
286
|
- **Stop conditions:**
|
|
@@ -319,7 +321,7 @@ Resolution options:
|
|
|
319
321
|
```
|
|
320
322
|
|
|
321
323
|
- **`repair`** — Fix the existing setup in place rather than replacing it. Delegate to the docs-analysis pack.
|
|
322
|
-
- **Allowed mutations (by this sub-procedure):** None directly. The bootstrap skill does not modify existing docs app files. It hands off to `oat-docs-analyze` (read-only audit)
|
|
324
|
+
- **Allowed mutations (by this sub-procedure):** None directly. The bootstrap skill does not modify existing docs app files. It hands off to `oat-docs-analyze` (read-only audit), then passes the analysis artifact plus approved recommendation IDs to `oat-docs-apply`; explicit items require individual approval.
|
|
323
325
|
- **Preserved state:** Existing docs app directory, the `documentation` config section, the root `AGENTS.md` `## Documentation` section — all preserved unless analyze surfaces a recommendation and the user approves it via apply.
|
|
324
326
|
- **Stop conditions:**
|
|
325
327
|
- Invoke `oat-docs-analyze` and surface its report to the user. If analyze cannot produce meaningful recommendations (e.g., `documentation.index` points at a missing file, or the app directory is empty), **stop the flow before Scaffold Runner**, report what analyze found, and ask the user whether to escalate to `replace`.
|
|
@@ -336,10 +338,10 @@ Preflight detected existing docs setup:
|
|
|
336
338
|
- existing-agents-section: AGENTS.md has a ## Documentation section
|
|
337
339
|
|
|
338
340
|
How should I proceed?
|
|
339
|
-
1.
|
|
340
|
-
2.
|
|
341
|
-
3.
|
|
342
|
-
4.
|
|
341
|
+
1. repair — default: run `oat-docs-analyze` / `oat-docs-apply` on the existing setup
|
|
342
|
+
2. replace — explicit choice required: remove the existing docs app and scaffold fresh
|
|
343
|
+
3. second-app — explicit choice required; deferred because current CLI cannot support it
|
|
344
|
+
4. abort — exit without changes
|
|
343
345
|
|
|
344
346
|
Choose:
|
|
345
347
|
```
|
|
@@ -351,10 +353,57 @@ Record the user's choice as `conflictResolution` in the Input Result. If the use
|
|
|
351
353
|
No matter which resolution the user picks, the Scaffold Runner (Step 3) **never** invokes `oat docs init` until:
|
|
352
354
|
|
|
353
355
|
1. The chosen resolution's "Allowed mutations" have **completed successfully**, and
|
|
354
|
-
2. The working-tree state **matches what the CLI expects** for that resolution (e.g., for `replace`: the target directory is empty or absent, the `documentation`
|
|
356
|
+
2. The working-tree state **matches what the CLI expects** for that resolution (e.g., for `replace`: the target directory is empty or absent, the `documentation` surface fields are cleared (any `guidance` input is preserved), the root `AGENTS.md` `## Documentation` section is cleared; for `abort` / `repair`: the skill has already exited).
|
|
355
357
|
|
|
356
358
|
If any mutation fails or any invariant check fails, **stop the flow before scaffold** and surface the error. A partial resolution followed by a scaffold produces a worse end state than either doing nothing or completing the resolution cleanly.
|
|
357
359
|
|
|
360
|
+
### Step 2.5: IA Discovery and Proposal
|
|
361
|
+
|
|
362
|
+
Run for fresh Markdown, Fumadocs and MkDocs setup, and explicit adoption, before
|
|
363
|
+
any scaffold invocation. An existing surface routed to repair takes this stage
|
|
364
|
+
through `oat-docs-analyze --ia`; it does not return to scaffold afterward.
|
|
365
|
+
|
|
366
|
+
1. Independently probe each exact `authoring-docs/SKILL.md` in order:
|
|
367
|
+
`${SKILL_DIR}/..` from the loaded skill (`SKILL_DIR` is the absolute directory
|
|
368
|
+
containing that loaded `SKILL.md`), `${HOME}/.agents/skills`, then
|
|
369
|
+
`<repo-root>/.agents/skills`. Bind the first matching `authoring-docs` directory
|
|
370
|
+
once as `AUTHORING_DOCS_ROOT`; load `${AUTHORING_DOCS_ROOT}/SKILL.md` and use
|
|
371
|
+
that same root for every authoring-docs reference and script, never ambient
|
|
372
|
+
discovery. If none is found, name `authoring-docs`, stop this handoff, and give
|
|
373
|
+
the intended-scope recovery command: `oat tools install docs --scope <user|project>`
|
|
374
|
+
or `oat tools update --pack docs --scope <user|project>`.
|
|
375
|
+
Read `${AUTHORING_DOCS_ROOT}/references/guidance-sources.md` and
|
|
376
|
+
`${AUTHORING_DOCS_ROOT}/references/information-architecture.md`.
|
|
377
|
+
Resolve explicit `--ia-guidance`/conversation → repo → user → built-in and
|
|
378
|
+
retain ordered locators/provenance. These are skill inputs, not new CLI flags.
|
|
379
|
+
2. Read repo signals: manifests, UI navigators and journeys, CLI `bin`, routers,
|
|
380
|
+
IaC, `e2e/` or `.maestro/`, existing docs, independently consumed monorepo units.
|
|
381
|
+
Read AGENTS/contributing authority first. Do not infer triad needs from UI alone.
|
|
382
|
+
3. Ask only decision-changing questions about readers/work contexts, independent
|
|
383
|
+
verification, canonical facts elsewhere and links that must survive.
|
|
384
|
+
4. Use the shared five axes and IA Proposal template to present **two plausible
|
|
385
|
+
candidate structures**, each a **two-level tree with 5–8 representative page
|
|
386
|
+
placements**, one page job per placement and the **nearest approved preset**.
|
|
387
|
+
Size controls materialized depth; it does not select audience. For Flat Small,
|
|
388
|
+
use grouped index headings rather than new directories.
|
|
389
|
+
5. Recommend one with evidence and tradeoffs; retain unresolved conflicts as
|
|
390
|
+
`ask_user` with local/external source citations. Non-repo guidance stays read-only
|
|
391
|
+
and private exemplars are never copied. Cite ordered sources in the proposal
|
|
392
|
+
and final summary, including the built-in path when it wins.
|
|
393
|
+
6. Obtain explicit approval of the selected IA before persistence. After setup,
|
|
394
|
+
use apply's `record-ia` procedure: target-repo `oat pjm doctor --json` and
|
|
395
|
+
adoption check before `oat decision new`, an Information architecture section
|
|
396
|
+
in the framework docs-app AGENTS.md or Markdown contributing page, and shared
|
|
397
|
+
`documentation.ia` mirror. Preserve existing guidance; the authored record is
|
|
398
|
+
authoritative. If approval/adoption is pending, retain the proposal and report
|
|
399
|
+
it unrecorded. Do not silently initialize PJM. For an existing surface, hand
|
|
400
|
+
off an analysis artifact plus approved recommendation IDs to apply, with
|
|
401
|
+
individual approval for explicit record/restructure/tooling items.
|
|
402
|
+
This stage does not materialize preset trees or change scaffold/nav defaults.
|
|
403
|
+
Sidebar ownership is separately chosen for existing framework apps; absent
|
|
404
|
+
remains undeclared, Markdown ignores it, and no automatic nav generation is
|
|
405
|
+
authorized by IA approval alone.
|
|
406
|
+
|
|
358
407
|
### Step 3: Scaffold Runner
|
|
359
408
|
|
|
360
409
|
Invoke `oat docs init` with the collected inputs and then apply gated post-patches for any CLI gaps the Capability Detection sub-procedure reports as still-open. The Scaffold Runner probes CLI capabilities, invokes the CLI, and applies the AGENTS.md bridge if still needed. Template content is CLI-owned; report old-scaffold shapes through `oat-docs-analyze`.
|
|
@@ -797,7 +846,13 @@ Delegate — do not re-implement analyze/apply logic here.
|
|
|
797
846
|
|
|
798
847
|
1. Invoke the `oat-docs-analyze` skill against the scaffolded app. Pass the Inspection Result's `documentation.root` path so analyze targets the right surface. Wait for analyze to complete.
|
|
799
848
|
2. Surface analyze's report to the user in its native form — do not re-summarize. The user reads it, decides which recommendations to approve.
|
|
800
|
-
3.
|
|
849
|
+
3. Capture the analysis artifact path and approved recommendation IDs, then
|
|
850
|
+
invoke `oat-docs-apply` with exactly that input. Preserve every approval class:
|
|
851
|
+
blanket approval covers only default items; explicit items need individual
|
|
852
|
+
approval by ID, and unattended runs skip/report them. Wait for apply's
|
|
853
|
+
structured applied/skipped-with-reason/failed IDs; report partial/manual work.
|
|
854
|
+
Never pass an unexplained "approved subset" or treat kickoff consent as
|
|
855
|
+
approval of every recommendation.
|
|
801
856
|
4. Report the outcome back briefly: branch name, PR URL if opened, files changed count.
|
|
802
857
|
|
|
803
858
|
If analyze produces no recommendations (the scaffold is complete and nothing's missing — unlikely on a fresh scaffold but possible), tell the user and skip apply.
|
|
@@ -826,6 +881,10 @@ OAT ▸ DOCS BOOTSTRAP COMPLETE
|
|
|
826
881
|
App: {appName}
|
|
827
882
|
Location: {appRoot}
|
|
828
883
|
Framework: {framework}
|
|
884
|
+
IA guidance: {ordered selected locators + explicit/conversation/shared/user/builtin provenance}
|
|
885
|
+
IA proposal: {candidate recommendation, nearest preset, conflicts or none}
|
|
886
|
+
IA record: {decision + authored section + shared mirror, or pending reason}
|
|
887
|
+
Apply handoff: {artifact path, approved IDs, applied/skipped/failed result or not run}
|
|
829
888
|
Config: {configPath} (documentation section)
|
|
830
889
|
|
|
831
890
|
Created:
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAIhF,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAoBzC,OAAO,EAUL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EAQnB,KAAK,UAAU,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}
|