Plans

# Note Starter Skill Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a `note-starter` skill that starts new-topic learning-note runs by delegating to `research-planner`.

**Architecture:** `note-starter` is a discoverable facade. It validates its scope, checks a possible existing run, and hands all context to the existing planner; the planner, orchestrator, and workflow retain write operations and phase transitions.

**Tech Stack:** Markdown, YAML, Python 3 skill-validation utilities, platform manifest validation, and the project synchronizer.

## Global Constraints

- Handle new-topic learning notes only; preserve established skills for old-note work.
- Create no command, workflow, state schema, or routing-table entry.
- Never overwrite `workspace/workflow-runs/{run_id}.workflow.md`.
- Declare only `Skill/research-planner` as a dependency and request read-only filesystem access.
- Sync Codex skill changes with the prescribed synchronizer; never edit `.claude/` directly.

---

## File Map

| Path | Responsibility |
| --- | --- |
| `.codex/skills/note-starter/SKILL.md` | Trigger description and concise scope, recovery, and planner handoff instructions. |
| `.codex/skills/note-starter/manifest.yaml` | Platform identity, permissions, capability, and dependency. |
| `.codex/skills/note-starter/agents/openai.yaml` | Generated UI metadata. |
| `AGENTS.md` | Natural-language skill-routing entry. |

### Task 1: Create and Register the Skill

**Files:** Create `.codex/skills/note-starter/SKILL.md`, `.codex/skills/note-starter/manifest.yaml`, and `.codex/skills/note-starter/agents/openai.yaml`.

- [ ] Verify absence: run `test ! -e .codex/skills/note-starter` and expect exit 0.
- [ ] Initialize the minimal skill directory with:

```bash
python3 /Users/zhqznc/.codex/skills/.system/skill-creator/scripts/init_skill.py note-starter \
  --path .codex/skills \
  --interface display_name="Note Starter" \
  --interface short_description="Start a structured note for a new topic" \
  --interface default_prompt='Use $note-starter to start a learning note about a new topic.'
```

- [ ] Replace the template with a prompt that requires a topic, redirects imports/single updates/batch updates to `legacy-note-importer`, `note-updater`, and `batch-note-updater`, reads routing, checks the lower-case hyphenated state-file name, recovers existing state without overwriting, delegates all supplied context to `research-planner`, and stops at the phase-0 confirmation boundary. Prohibit research, writing, Obsidian publishing, MOC updates, and manual phase advancement.
- [ ] Create this manifest:

```yaml
apiVersion: agents.study-system/v1
kind: Skill
metadata:
  name: note-starter
  version: 1.0.0
  description: "Start a new-topic learning note through the existing planner and workflow."
spec:
  entrypoint: SKILL.md
  capabilities:
    - notes.start
  permissions:
    filesystem: read
    network: none
    subprocess: none
    git: none
  dependsOn:
    - Skill/research-planner
  lifecycle:
    discoverable: true
    deprecated: false
```

- [ ] Verify with `quick_validate.py .codex/skills/note-starter` and `python3 .codex/platform/manifest-registry.py --root . validate`; both must exit 0.

### Task 2: Add Routing and Synchronize

**Files:** Modify `AGENTS.md`; verify generated mirror output.

- [ ] Verify the route is initially absent with `rg -n 'note-starter|开始写笔记|启动写笔记|创建学习笔记' AGENTS.md || true`.
- [ ] Add the following row immediately before `research-planner` in `Skill Routing`:

```markdown
| `note-starter` | 开始写笔记、启动写笔记、创建学习笔记、新主题笔记、start a learning note |
```

- [ ] Run `rg -n 'note-starter|开始写笔记|启动写笔记|创建学习笔记' AGENTS.md`, `.codex/scripts/sync-codex-to-claude.sh`, and `.codex/scripts/sync-codex-to-claude.sh --check`; all must succeed.

### Task 3: Verify and Commit

- [ ] Run `rg -n '旧笔记|legacy-note-importer|note-updater|batch-note-updater|research-planner|learning-note-flow|workflow-runs|不.*研究|不.*写' .codex/skills/note-starter/SKILL.md` to inspect each guardrail.
- [ ] Run `git diff --check`, `python3 .codex/platform/manifest-registry.py --root . validate`, and `.codex/scripts/sync-codex-to-claude.sh --check`; all must exit 0.
- [ ] Stage `AGENTS.md`, `.codex/skills/note-starter`, and only the mirror files generated by sync. Commit with `git commit -m "feat: add note starter skill"`.