@codio-ai/opencode-authoring-agent 0.1.0

package/src/skills/reference-page-flow/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: reference-page-flow
+description: Page sequence patterns — intro / objectives / instructional / assessment / conclusion ordering. Use when designing assignment structure or planning page types.
+---
+
+# Page flow patterns
+
+This reference is loaded by `outline-architect` and `page-author`. It defines standard sequences of page types for common assignment shapes.
+
+## Default sequence (apply when user gives no other instruction)
+
+1. **Introduction** — sets context, motivation, and what the assignment will cover. Short. No assessment.
+2. **Objectives** — lists what learners will know or be able to do after completing the assignment. One bulleted list, derived from the learning objectives provided at intake.
+3. **Instructional pages** — one or more pages, each focused on one concept or sub-skill. Roughly one LO per page when the assignment is well-decomposed.
+4. **Formative assessment(s)** — embedded MCQs on a dedicated assessment page, OR embedded inline at the end of the relevant instructional page. Single approach per assignment unless the user requests otherwise.
+5. **Conclusion / summary** — reinforces the most important concepts and points to next steps. No assessment.
+
+## Variants
+
+### Lab-style assignment (heavy hands-on)
+
+```
+Introduction → Objectives → Setup page (workspace files) → Walkthrough page(s) → Try-it-yourself page (with custom button) → Assessment → Conclusion
+```
+
+Use `2-panels-tree` layout for any page with workspace files; `1-panel` for purely conceptual pages.
+
+### Assessment-only assignment (review/quiz)
+
+```
+Introduction → Objectives → Assessment page(s) → Conclusion
+```
+
+Skip instructional pages entirely.
+
+### Multi-chapter assignment
+
+Each chapter follows the default sequence internally. The root `index.json` `order` array references chapter folders; each chapter's `index.json` references its pages.
+
+## Chaptering rules
+
+- Use chapters when the assignment has ≥ 2 distinct topic groupings AND ≥ ~6 pages total.
+- Don't chapter a 3-page assignment. The overhead exceeds the navigational value.
+- Within a chapter, follow the default sequence; the introduction and conclusion can be at the assignment level (outside chapters) or per-chapter, depending on size.
+
+## Page type → layout default
+
+| Page type | Default layout | Files array |
+|---|---|---|
+| Introduction | `1-panel` | `[]` |
+| Objectives | `1-panel` | `[]` |
+| Instructional (concept only) | `1-panel` | `[]` |
+| Instructional (with code/workspace files) | `2-panels-tree` | `[ { "path": "<file>", "panel": 0, "action": "open" } ]` |
+| Assessment | `1-panel` | `[]` |
+| Conclusion | `1-panel` | `[]` |
+
+## When to deviate from defaults
+
+The defaults exist to prevent decision fatigue, not to enforce rigidity. Override when:
+- The user provided their own structure — follow theirs.
+- The topic is intrinsically asymmetric (e.g. "one big tutorial then ten exercises" — flatten the instructional bundle, expand the assessment side).
+- The audience profile suggests it (e.g. expert audience needs less introduction; novice audience needs more scaffolding pages).

package/src/skills/reference-project-defaults/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: reference-project-defaults
+description: Default field values and sequences for Codio assignments (points, max_attempts, layout defaults).
+---
+
+# Project defaults
+
+Apply these defaults unless the user overrides them.
+
+## Root index.json defaults
+
+```json
+{
+  "theme": "light",
+  "useSubmitButtons": true,
+  "useMarkAsComplete": false,
+  "hideMenu": false,
+  "allowGuideClose": false,
+  "protectLayout": false,
+  "suppressPageNumbering": true,
+  "collapsedOnStart": false,
+  "hideSectionsToggle": false,
+  "hideBackToDashboard": false
+}
+```
+
+## Page layout defaults
+
+- Pages with workspace files: `"layout": "2-panels-tree"`
+- Conceptual pages without files: `"layout": "1-panel"`
+- `"teacherOnly": false` unless the page is instructor-only content
+
+## Assessment defaults
+
+- `"isRandomized": true` — shuffle answer order
+- `"multipleResponse": false` — single correct answer unless the user requests otherwise
+- `"maxAttemptsCount": 1`
+- `"showGuidanceAfterResponseOption": { "type": "Attempts", "passedFrom": 1 }` — show guidance after first attempt
+- `"showExpectedAnswerOption": { "type": "Always" }`
+- `"points": 20`
+- `"incorrectPoints": 0`
+- `"arePartialPointsAllowed": false`
+- `"guidance"` should contain a brief explanation of why the correct answer is right and why each distractor is wrong, when the topic supports it
+
+## Custom buttons
+
+- Add process-launch buttons only when the assignment includes runnable code or commands.
+- Do not add section buttons.
+- Use `| terminal` when the program reads standard input.
+- Keep labels short and action-oriented: `Run Code`, `Compile & Run`, `Run Tests`.
+
+## Page flow
+
+Standard page sequence when not otherwise specified:
+
+1. Introduction
+2. Objectives
+3. Instructional content pages (one or more)
+4. Formative assessment page(s)
+5. Conclusion / summary
+
+## Formatting
+
+- Suppress page numbering in titles (`suppressPageNumbering: true`)
+- Use callout blocks (`|||info`, `|||important`, etc.) for tips, warnings, and key definitions
+- Use fenced code blocks with language labels for all code samples
+- Keep prose clear, direct, and student-friendly
+
+## Deliverable
+
+- Files are written directly into the live Codio workspace as they are generated.
+- Tooling itself lives in `.guides/secure/codio-authoring-opencode/` (hidden from students).
+
+## Interpretation notes
+
+- Follow explicit user constraints over these defaults.
+- Do not impose fixed chapter counts, page counts, or word counts unless the user asked for them.
+- Do not impose fixed attempts or feedback timing unless the user asked for them.
+- When the topic is conceptual, do not add custom buttons.
+- When the topic includes programming, add buttons only if they clearly support the learning activity.

package/src/skills/reference-style/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: reference-style
+description: Style guide for codio guide prose — concise sentences, active voice, callout usage, code block conventions, LaTeX math.
+---
+
+# Codio guide style
+
+- Concise instructional prose. Short sentences. Active voice. Address the learner directly ("you", not "the student").
+- Use callout blocks (`|||info`, `|||important`, `|||warning`, `|||definition`) for tips, warnings, and key definitions — not as decoration.
+- Fenced code blocks always include a language label.
+- Use LaTeX (`$...$` inline, `$$...$$` block) for math.
+- Suppress page numbering in titles.
+- Cross-page references use the page title verbatim (not "previous/next page" — page order can change).
+- No filler ("In this section, we will explore…"). Get to the point.

package/src/skills/workflow-add-assessment/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: workflow-add-assessment
+description: Use when the user wants to add one or more assessments to an existing page (multiple-choice / code-output-compare / fill-in-the-blanks). Example intents — "add an MCQ about X", "add a coding exercise on Y", "add 3 questions on W", "add a fill-in-the-blanks question". Needs type + topic + target page.
+---
+
+# Workflow: add-assessment
+
+Add one or more assessments to an existing page.
+
+## Intake
+
+Confirm:
+1. **Assessment type** — `multiple-choice`, `code-output-compare`, or `fill-in-the-blanks`. If the user says only "add a question," ask which type.
+2. **Topic / focus** — what the assessment(s) should test.
+3. **Target page stem**.
+4. **Count** — default 3 for MCQ; 1 for code test / FITB.
+
+## Steps
+
+1. Read the target page's `.md` for context.
+2. Dispatch `@assessment-author` (parallel when count ≥ 2) with type, topic, LO (read from the page's JSON), and count.
+3. For each returned payload: call `create_assessment` → splice the returned `embedLine` into the page markdown.
+4. If 2+ embeds and the page doesn't already have a "Check your understanding" heading, add one and group the embeds under it.
+5. **Skip auto-validation** — low risk for a focused add.
+
+## Rules
+
+- Auto-run when type + topic + target are clear.
+- When count ≥ 2, fan out `@assessment-author` calls in parallel.

package/src/skills/workflow-add-page/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: workflow-add-page
+description: Use when the user wants to add one new page to an existing Codio assignment. Example intents — "add a page on X", "write a page titled Y in chapter Z", "add an instructional page about W". Needs title + parent (root or chapter folder).
+---
+
+# Workflow: add-page
+
+Add a single page to an existing assignment.
+
+## Intake
+
+Confirm:
+1. **Title**
+2. **Parent** — root or the chapter folder name (if assignment is single-chapter, default to the chapter unless told root).
+3. **Type** — `intro`, `objectives`, `instructional`, `assessment`, or `conclusion`. Default `instructional`.
+4. **Layout** — `1-panel` or `2-panels-tree`. Default `1-panel`; if `2-panels-tree`, ask for `files`.
+5. **Learning objective(s)** — at least one. If the user defers, propose candidates and confirm.
+6. **Body brief** — bullets of what the page should cover.
+
+## Steps
+
+1. Generate stem (kebab-slug of title + 4-hex).
+2. Read parent's `index.json` to confirm the page doesn't collide; note current `order`.
+3. Dispatch `@page-author` (draft mode) with the brief.
+4. Call `create_page` with the returned body + metadata.
+5. Update parent `index.json` — append the new stem to `order` using the edit tool.
+6. **Skip auto-validation** — single-page add is low-risk. User can run `/validate-guide` manually.
+
+## Rules
+
+- Auto-run when title + parent are clear.
+- If type or LO is missing, ask inline. Do not bounce to a different workflow.

package/src/skills/workflow-import-source/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: workflow-import-source
+description: Use when the user provides source material (file path, URL, or paste) and wants pages built from it. Example intents — "import this material", "ingest <path or URL>", "use this source to build pages". Default materials location is `.guides/secure/materials/`.
+---
+
+# Workflow: import-source
+
+Ingest source material and build pages from it.
+
+## Intake
+
+Confirm:
+1. **Source** — path (default lookup under `.guides/secure/materials/` if relative), URL, or paste.
+2. **Scope** — building a fresh assignment, or appending pages to an existing one?
+3. **Focus** (optional) — concepts, examples, exercises.
+
+## Steps (fresh assignment)
+
+Run `workflow-new-assignment`, but in Stage 2 dispatch `@source-ingester` with the source. The digest feeds Stage 3 (`@outline-architect`).
+
+## Steps (appending)
+
+1. Dispatch `@source-ingester` with the source.
+2. Show the digest to the user. Ask which pages they want to add (or have `@outline-architect` propose additions, with approval).
+3. For each new page: run `workflow-add-page` (intake skipped — you already have the brief).
+4. Auto-run `validate_guide` at the end (multi-page change).
+
+## Rules
+
+- Outline gate applies to fresh-assignment branch (delegated to `workflow-new-assignment`).
+- Appending branch confirms additions in one batch before writing.

package/src/skills/workflow-new-assignment/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: workflow-new-assignment
+description: Use when the user wants to start a new Codio assignment from scratch — building it from intake (topic, audience, LOs) through outline approval, scaffolding, page drafting, assessments, and validation. Example intents — "start a new assignment about X", "build a guide on Y", "create a course on Z". Assignments are flat or single-chapter only.
+---
+
+# Workflow: new-assignment
+
+End-to-end pipeline for authoring a new Codio assignment. Single approval gate at outline. Drives the full staged pipeline; after approval, runs end-to-end.
+
+## Stage 1: Intake
+
+Ask for (do not skip even if the user's first message had some of these):
+
+1. **Topic**
+2. **Audience** — level, prior knowledge.
+3. **Learning objectives** — if the user has none, say so; `@outline-architect` will propose candidates.
+4. **Structural constraints** — page count, assessment count, anything fixed. Note: assignment is flat or single-chapter.
+5. **Source materials** — file path under `.guides/secure/materials/`, URL, or paste. If none, note "design from scratch."
+
+Detect existing assignment: if `.guides/content/index.json` exists with non-empty `order`, this is **not** a new assignment. Tell the user; ask whether they want to import additional source material (append), revise an existing page, or add new pages — then route to the matching workflow skill. Stop the new-assignment workflow.
+
+## Stage 2: Source ingestion (conditional)
+
+If the user provided materials, dispatch `@source-ingester` with each. Collect the digest(s). Otherwise skip.
+
+## Stage 3: Outline
+
+Dispatch `@outline-architect` with topic, audience, LOs, structural constraints, and any source digests. The architect returns a markdown outline (flat or single-chapter).
+
+**APPROVAL GATE.** Show the outline to the user. Iterate. Do not proceed until the user approves.
+
+## Stage 4: Mechanical scaffolding
+
+Once approved:
+
+1. Generate stems (kebab-slug + 4-hex) for every page (and the chapter folder, if single-chapter).
+2. Build a planning map: `{ stem → { title, type, layout, lo, parent (root or chapter folder), needs_assessment, mcq_topic } }`.
+3. Write `.guides/content/index.json` with title, defaults (see `reference-project-defaults` skill), and the root-level `order` (chapter folder + any non-chaptered pages, in order).
+4. If single-chapter: create `.guides/content/<chapter-folder>/index.json` with its own `order`.
+
+## Stage 5: Fan-out drafting
+
+Dispatch `@page-author` (draft mode) **in parallel** — one call per page. Each call gets stem, title, type, layout, LO(s), body brief, and `assignment_context`.
+
+Each `@page-author` returns body+metadata. You call `create_page` for each. No assessment embeds yet.
+
+## Stage 6: Assessments
+
+For each page flagged `needs_assessment`, dispatch `@assessment-author` (parallel when ≥2). Default `assessment_type: multiple-choice` unless the outline says otherwise; pass the page's LO, inferred topic, body for context, and `count` (default 3 for MCQ; usually 1 for code test / FITB).
+
+After each return, call `create_assessment` with the payload, then splice the returned `embedLine` into the corresponding page markdown using the edit tool. Group multiple embeds under `## Check your understanding`.
+
+## Stage 7: Validation
+
+Call the `validate_guide` tool. If structural findings exist, surface them.
+
+Optionally dispatch `@validator` for content review. If the validator flags content-quality issues, present them and pause. The user can ask you to address each — route via the relevant workflow skill (`workflow-revise-page` or `workflow-add-assessment`).
+
+## Stage 8: Done
+
+Summarize: title, page count (and chapter, if any), assessment count, validation status, suggested next actions.
+
+## Rules
+
+- Only ONE approval gate — Stage 3.
+- Never write to `.guides/content/` or `.guides/assessments/` before Stage 3 is passed.
+- Parallelism only within Stages 5 and 6.
+- If any subagent or tool call fails, surface and stop. Do not silently continue.
+- Assignment is flat or single-chapter. Never propose multi-chapter.

package/src/skills/workflow-reorder/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: workflow-reorder
+description: Use when the user wants to change page or section ordering. Example intents — "reorder X", "move chapter Y before Z", "rearrange pages". Always confirm new position before writing. Modifies `order` arrays in index.json.
+---
+
+# Workflow: reorder
+
+Change page or section ordering.
+
+## Intake
+
+Confirm in one sentence: "Moving <X> to position <N> in <parent>. Proceed?" Wait for the user to confirm or correct.
+
+## Steps
+
+1. Read the relevant `index.json` (root or chapter folder).
+2. Update the `order` array using the edit tool.
+3. If reordering touches multiple parents (e.g. moving a page out of the chapter to root), update both index files.
+4. Auto-run `validate_guide` (touches `order` arrays — exactly what the validator checks).
+
+## Rules
+
+- **Always confirm.** Restate the new position before writing.
+- Auto-validate after every reorder.

package/src/skills/workflow-revise-page/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: workflow-revise-page
+description: Use when the user wants to edit an existing page — surgical changes to prose, examples, or callouts. Example intents — "revise the page on X", "rewrite the section about Y", "edit the page about Z". Auto-runs for additive edits; confirms before prose-overwriting changes.
+---
+
+# Workflow: revise-page
+
+Edit an existing page.
+
+## Intake
+
+Confirm:
+1. **Page stem**.
+2. **Change** — description of what to modify (free-form). Categorize:
+   - **Additive** — append/insert (e.g. "add a worked example", "add a note about edge cases"). Auto-run.
+   - **Surgical replacement** — replace a paragraph or section. Restate ("I'll replace the second paragraph with ..."), then proceed unless corrected.
+   - **Wholesale rewrite** — if the change amounts to a rewrite, ask whether to switch to draft mode (start the page over) instead.
+
+## Steps
+
+1. Dispatch `@page-author` (revise mode) with `stem` and `change`.
+2. `@page-author` reads the existing `.md`, applies the smallest contiguous edit, and returns a one-line summary.
+3. If the change requires a new assessment embed, do NOT splice it here — `@page-author` returns the request, and you dispatch `workflow-add-assessment` for that page.
+4. **Skip auto-validation** — surgical edit; validator likely has nothing to flag.
+
+## Rules
+
+- Auto-run additive edits.
+- Restate replacements; proceed unless corrected.
+- Bounce wholesale rewrites back to the user for explicit confirmation before switching to draft mode.