pi-maestro-flow 0.2.0

package/skills/scholar-writing/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: scholar-writing
+description: "End-to-end academic paper writing workflow. Takes a research repository and produces a publication-ready LaTeX manuscript for top ML/AI conferences (NeurIPS, ICML, ICLR, ACL, AAAI, COLM). Covers repo understanding, structure planning, section drafting, citation management, anti-AI polishing, and conference formatting. Triggers on \"write paper\", \"draft paper\", \"scholar writing\", \"paper writing workflow\"."
+allowed-tools: Read Write Edit Bash Glob Grep WebSearch WebFetch TodoWrite AskUserQuestion Task
+---
+
+# Scholar Writing
+
+End-to-end workflow for writing publication-ready ML/AI papers from research repositories. Integrates paper writing craft, citation verification, and anti-AI polishing into a structured 6-phase pipeline.
+
+## Pre-load (before execution)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for project context
+2. **Specs**: `maestro load --type spec --category coding` — load coding conventions
+3. **Wiki knowledge**: `maestro search "academic writing research paper" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## Architecture Overview
+
+```
+User: "Write a paper from this repo"
+         |
+         v
+┌──────────────────────────────────────────────────────────────────────┐
+│  SKILL.md (Orchestrator)                                             │
+│  Collect preferences → Dispatch phases → Track progress              │
+└──────────┬───────────────────────────────────────────────────────────┘
+           |
+   ┌───────┼───────┬───────────┬──────────┬──────────┬────────────┐
+   v       v       v           v          v          v            v
+┌──────┐┌──────┐┌──────────┐┌──────────┐┌──────────┐┌──────────────┐
+│ P1   ││ P2   ││ P3       ││ P4       ││ P5       ││ P6           │
+│ Repo ││Struct││ Section  ││ Citation ││ Anti-AI  ││ Conference   │
+│ Under││Plan  ││ Drafting ││ Manage   ││ Polish   ││ Formatting   │
+└──┬───┘└──┬───┘└────┬─────┘└────┬─────┘└────┬─────┘└──────┬───────┘
+   │       │         │           │           │             │
+   v       v         v           v           v             v
+ repo    outline   full draft   verified    polished     paper.tex
+ context  + plan               .bib file   prose        (camera-ready)
+```
+
+## Key Design Principles
+
+1. **Proactive drafting**: Deliver complete drafts, then iterate on feedback. Do not block on every section.
+2. **Never hallucinate citations**: Every citation must be verified via WebSearch and Google Scholar. Mark unverifiable references as `[CITATION NEEDED]`.
+3. **Narrative-first writing**: A paper is a story with one clear contribution. Define the What/Why/So What before writing.
+4. **Anti-AI polish is mandatory**: All prose passes through pattern detection and humanization before final output.
+5. **Conference-aware from start**: Target venue influences page limits, required sections, and framing.
+
+## Interactive Preference Collection
+
+Before dispatching to any phase, collect these preferences:
+
+```
+Questions to ask the user:
+
+1. Research Repository
+   "Where is the research repo? (path or URL)"
+   → repoPath
+
+2. Target Conference
+   Options: NeurIPS | ICML | ICLR | ACL | AAAI | COLM | Other
+   → targetConference
+
+3. Paper Type
+   Options: Full Paper | Short Paper | Workshop Paper
+   → paperType
+
+4. Output Directory
+   "Where should the paper be written? (default: ./paper/)"
+   → outputDir
+
+5. Existing Materials
+   "Any existing drafts, notes, or outlines to build on? (path or 'none')"
+   → existingMaterials
+
+6. Writing Language
+   Options: English | Chinese | Bilingual
+   → writingLanguage
+```
+
+Store responses as `paperPreferences` context for all phases.
+
+## Auto Mode Defaults
+
+When `workflowPreferences.autoYes === true`:
+- Use detected repo path from cwd
+- Default to NeurIPS format, Full Paper, English
+- Output to `./paper/`
+- Skip confirmation prompts within phases
+
+## Execution Flow
+
+> **COMPACT DIRECTIVE**: Context compression MUST check TodoWrite phase status.
+> The phase currently marked `in_progress` is the active execution phase -- preserve its FULL content.
+> Only compress phases marked `completed` or `pending`.
+
+### TodoWrite Setup
+
+```
+Paper Writing Workflow:
+- [ ] Phase 1: Repo Understanding — explore repo, identify contribution
+- [ ] Phase 2: Structure Planning — plan outline, define narrative
+- [ ] Phase 3: Section Drafting — write all sections
+- [ ] Phase 4: Citation Management — find, verify, format citations
+- [ ] Phase 5: Anti-AI Polish — remove AI patterns, humanize prose
+- [ ] Phase 6: Conference Formatting — apply template, compile
+```
+
+### Phase Sequence
+
+```
+Phase 1: Repo Understanding
+   └─ Ref: phases/01-repo-understanding.md
+      ├─ Input: repoPath, existingMaterials
+      └─ Output: repoContext (contribution, results, existing citations)
+
+Phase 2: Structure Planning
+   └─ Ref: phases/02-structure-planning.md
+      ├─ Input: repoContext, targetConference, paperType
+      └─ Output: paperOutline (section plan, narrative arc, page budget)
+
+Phase 3: Section Drafting
+   └─ Ref: phases/03-section-drafting.md
+      ├─ Input: repoContext, paperOutline, writingLanguage
+      └─ Output: draftSections (all sections as LaTeX content)
+
+Phase 4: Citation Management
+   └─ Ref: phases/04-citation-management.md
+      ├─ Input: draftSections, repoContext.existingCitations
+      └─ Output: verifiedBib (references.bib), updatedDraft (citations resolved)
+
+Phase 5: Anti-AI Polish
+   └─ Ref: phases/05-anti-ai-polish.md
+      ├─ Input: updatedDraft
+      └─ Output: polishedDraft (humanized prose, AI patterns removed)
+
+Phase 6: Conference Formatting
+   └─ Ref: phases/06-conference-formatting.md
+      ├─ Input: polishedDraft, verifiedBib, targetConference
+      └─ Output: paper.tex (complete manuscript ready for compilation)
+```
+
+**Phase Reference Documents** (read on-demand when phase executes):
+
+| Phase | Document | Purpose | Compact |
+|-------|----------|---------|---------|
+| 1 | [phases/01-repo-understanding.md](phases/01-repo-understanding.md) | Explore repo, identify contribution | TodoWrite driven |
+| 2 | [phases/02-structure-planning.md](phases/02-structure-planning.md) | Plan outline, define narrative | TodoWrite driven |
+| 3 | [phases/03-section-drafting.md](phases/03-section-drafting.md) | Write all paper sections | TodoWrite driven + sentinel |
+| 4 | [phases/04-citation-management.md](phases/04-citation-management.md) | Find, verify, format citations | TodoWrite driven + sentinel |
+| 5 | [phases/05-anti-ai-polish.md](phases/05-anti-ai-polish.md) | Remove AI patterns, humanize | TodoWrite driven + sentinel |
+| 6 | [phases/06-conference-formatting.md](phases/06-conference-formatting.md) | Apply template, compile | TodoWrite driven |
+
+**Compact Rules**:
+1. **TodoWrite `in_progress`** → preserve full content, do not compress
+2. **TodoWrite `completed`** → may compress to summary
+3. **sentinel fallback** → phases marked with sentinel contain compact sentinel; if only sentinel remains after compression, **must immediately `Read()` to recover before continuing**
+
+## Core Rules
+
+1. **Citation integrity**: NEVER generate BibTeX from memory. Always verify via WebSearch + Google Scholar. Mark unverifiable as `[CITATION NEEDED]`.
+2. **One contribution**: The paper tells one story. Every section supports the central narrative.
+3. **Proactive delivery**: Write full drafts, flag uncertainties. Do not block waiting for per-section approval.
+4. **Conference compliance**: Respect page limits, required sections, and anonymization requirements.
+5. **Anti-AI mandatory**: All prose must pass anti-AI pattern detection before final output.
+
+## Input Processing
+
+User input is parsed into `paperPreferences`:
+
+```
+REPO: [path to research repository]
+CONFERENCE: [NeurIPS | ICML | ICLR | ACL | AAAI | COLM]
+TYPE: [Full | Short | Workshop]
+OUTPUT: [output directory path]
+MATERIALS: [path to existing drafts or 'none']
+LANGUAGE: [English | Chinese | Bilingual]
+```
+
+If user provides free text like "write a paper about my transformer project", extract:
+- Repo path from context or ask
+- Default conference to NeurIPS
+- Default type to Full Paper
+- Default language to English
+
+## Data Flow
+
+```
+Phase 1 ──repoContext──→ Phase 2
+Phase 2 ──paperOutline──→ Phase 3
+Phase 1 ──repoContext──→ Phase 3
+Phase 3 ──draftSections──→ Phase 4
+Phase 4 ──updatedDraft + verifiedBib──→ Phase 5
+Phase 5 ──polishedDraft──→ Phase 6
+Phase 4 ──verifiedBib──→ Phase 6
+
+Data persistence: All intermediate outputs written to outputDir/
+  outputDir/.writing/
+  ├── repo-context.md        (Phase 1 output)
+  ├── paper-outline.md       (Phase 2 output)
+  ├── drafts/                (Phase 3 output)
+  │   ├── abstract.tex
+  │   ├── introduction.tex
+  │   ├── methods.tex
+  │   ├── experiments.tex
+  │   ├── related-work.tex
+  │   ├── conclusion.tex
+  │   └── appendix.tex
+  ├── references.bib         (Phase 4 output)
+  ├── polished/              (Phase 5 output)
+  │   └── (same structure as drafts/)
+  └── paper.tex              (Phase 6 output)
+```
+
+## TodoWrite Pattern
+
+### Phase Start (Attach)
+```
+When Phase N begins:
+  → Mark Phase N as in_progress in TodoWrite
+  → Add sub-tasks for Phase N steps
+  → Execute sub-tasks sequentially
+```
+
+### Phase End (Collapse)
+```
+When Phase N completes:
+  → Mark all Phase N sub-tasks as completed
+  → Collapse to summary: "Phase N complete: [key output]"
+  → Mark Phase N+1 as in_progress
+```
+
+## Post-Phase Updates
+
+Between phases, update a running paper-notes document:
+
+```markdown
+# Paper Writing Notes (accumulated)
+
+## Contribution (Phase 1)
+[One-sentence contribution statement]
+
+## Outline (Phase 2)
+[Section structure with page budgets]
+
+## Draft Status (Phase 3)
+[Section completion status]
+
+## Citation Status (Phase 4)
+[Verified count / placeholder count]
+
+## Polish Status (Phase 5)
+[Anti-AI score per section]
+```
+
+Written to: `outputDir/.writing/paper-notes.md`
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Repo path invalid | Ask user for correct path |
+| Cannot identify contribution | Present top 3 candidates, ask user to choose |
+| Citation not found | Mark `[CITATION NEEDED]`, continue, report at end |
+| LaTeX compilation fails | Fix common errors (missing packages, encoding), retry once |
+| Anti-AI score below 35 | Re-polish section, flag for manual review |
+| Page limit exceeded | Suggest specific cuts (move proofs to appendix, condense related work) |
+
+## Coordinator Checklist
+
+### Before Each Phase
+- [ ] Previous phase output exists and is valid
+- [ ] TodoWrite updated (current phase in_progress)
+- [ ] Required inputs available
+
+### After Each Phase
+- [ ] Output files written to outputDir/.writing/
+- [ ] paper-notes.md updated
+- [ ] TodoWrite collapsed (phase completed)
+- [ ] User notified of phase completion and key decisions made
+
+### Final Checklist
+- [ ] All 6 phases completed
+- [ ] paper.tex compiles without errors
+- [ ] All citations verified (no remaining `[CITATION NEEDED]`)
+- [ ] Anti-AI score >= 35 for all sections
+- [ ] Page limit respected
+- [ ] Anonymization applied (for blind review)
+- [ ] Conference checklist completed (if required)
+
+## Related Skills
+
+- **scholar-ideation**: Use before this skill to develop research ideas
+- **scholar-experiment**: Use before this skill to run experiments
+- **scholar-review**: Use after this skill to review/revise the paper

package/skills/security-audit/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: security-audit
+description: "OWASP Top 10 and STRIDE security auditing with supply chain analysis Arguments: [quick|standard|deep] [--scope <path>]"
+allowed-tools: Read Write Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Systematic security audit covering OWASP Top 10, dependency supply chain, secrets detection,
+CI/CD pipeline review, and optional STRIDE threat modeling. Three tiers control depth vs speed.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/review.md
+</required_reading>
+
+<context>
+$ARGUMENTS — Parse tier and scope:
+- Tier: `quick` (default) | `standard` | `deep`
+- `--scope <path>`: Limit scan to directory (default: project root)
+
+**Tier coverage:**
+
+| Tier | OWASP | Dependencies | Secrets | CI/CD | STRIDE | Git History |
+|------|-------|-------------|---------|-------|--------|-------------|
+| quick | ✓ | ✓ | — | — | — | — |
+| standard | ✓ | ✓ | ✓ | ✓ | — | — |
+| deep | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-security-audit-{tier}-{slug}/` or `.workflow/state.json` only. NEVER modify source code, configuration files, or dependencies. Audit is read-only analysis.
+</context>
+
+<invariants>
+1. **Audit is read-only** — NEVER modify source code, configuration, dependencies, or CI/CD files during audit. Security audit produces reports only.
+2. **Findings require file:line evidence** — every finding MUST reference a specific file:line location and include the vulnerable code pattern. No vague or category-only findings.
+3. **Severity NEVER downgraded without justification** — if a finding matches a known OWASP category, its severity follows OWASP guidance. Downgrading requires documented rationale (e.g., compensating control exists).
+4. **Tier coverage is mandatory** — all scan phases required by the selected tier MUST complete. NEVER skip a tier-required phase silently; failures are logged as W00x warnings.
+5. **False positive marking requires evidence** — marking a finding as false positive MUST include the compensating control or code path that prevents exploitation. NEVER dismiss findings without counter-evidence.
+6. **Secrets are never logged** — if secrets are discovered, report their location (file:line) and type but NEVER include the actual secret value in the report output.
+</invariants>
+
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Recon → Scan**
+- REQUIRED: Tech stack detected and entry points identified.
+- REQUIRED: Auth/authz modules listed and data flow mapped.
+- BLOCKED if missing: cannot scan without entry points and data flow baseline.
+
+**GATE 2: Scan → Report** (tier-gated)
+- REQUIRED: OWASP Top 10 scan completed (all tiers).
+- REQUIRED: Dependency audit completed (all tiers).
+- REQUIRED: Secrets + CI/CD scan completed (standard/deep only).
+- REQUIRED: STRIDE + git history completed (deep only).
+- BLOCKED if tier-required scans incomplete: finish all tier-applicable phases before reporting.
+
+**GATE 3: Report → Completion**
+- REQUIRED: Severity matrix produced with file:line references and remediation.
+- REQUIRED: Artifact registered in state.json.
+- BLOCKED if missing: do not emit completion status without severity matrix.
+
+**Phase 1: Reconnaissance**
+
+1. Detect tech stack from package.json / go.mod / requirements.txt / Cargo.toml
+2. Identify entry points: HTTP handlers, API routes, CLI parsers, WebSocket handlers
+3. List authentication/authorization modules
+4. Map data flow: user input → processing → storage → output
+
+**Phase 2: OWASP Top 10 Scan** (all tiers)
+
+For each category, scan relevant source files:
+
+| # | Category | What to check |
+|---|----------|--------------|
+| A01 | Broken Access Control | Missing auth middleware, direct object references, path traversal |
+| A02 | Cryptographic Failures | Weak algorithms, hardcoded keys, missing TLS, plaintext storage |
+| A03 | Injection | SQL concatenation, shell exec with user input, template injection |
+| A04 | Insecure Design | Missing rate limits, no CSRF tokens, predictable tokens |
+| A05 | Security Misconfiguration | Debug mode, default credentials, verbose errors, open CORS |
+| A06 | Vulnerable Components | Known CVEs in dependencies |
+| A07 | Auth Failures | Weak password rules, missing brute-force protection, session fixation |
+| A08 | Data Integrity | Deserialization of untrusted data, unsigned updates |
+| A09 | Logging Failures | Missing audit logs, logging sensitive data |
+| A10 | SSRF | Unvalidated URLs in server-side requests |
+
+Use `Grep` for pattern matching (e.g., `eval(`, `exec(`, `innerHTML`, `dangerouslySetInnerHTML`,
+`sql.*\+.*req\.`, `process\.env` without validation).
+
+**Phase 3: Dependency Audit** (all tiers)
+
+```bash
+# Node.js
+npm audit --json 2>/dev/null || true
+# Check lockfile integrity
+test -f package-lock.json && echo "lockfile present" || echo "WARNING: no lockfile"
+```
+
+Check for:
+- Known vulnerabilities (CVE references)
+- Lockfile presence and integrity
+- Typosquatting risk on critical dependencies (manually check suspicious names)
+
+**Phase 4: Secrets Detection** (standard + deep)
+
+```
+Grep({
+  pattern: "(password|secret|api.?key|token|credential).*=.*['\"][^'\"]{8,}",
+  glob: "*.{ts,js,json,env*}",
+  output_mode: "content"
+})
+```
+
+Check `.env.example` for leaked values. Check `.gitignore` for missing `.env` patterns.
+
+**Phase 5: CI/CD Audit** (standard + deep)
+
+Scan `.github/workflows/*.yml` for:
+- Overly permissive `permissions:` (write-all, contents: write)
+- Unpinned action versions (`uses: actions/checkout@main` vs `@v4.1.0`)
+- Secrets in logs (missing `mask` or `add-mask`)
+- Pull request trigger with `pull_request_target` (code injection risk)
+
+**Phase 6: STRIDE Threat Modeling** (deep only)
+
+For each critical module identified in Phase 1:
+
+| Threat | Question |
+|--------|----------|
+| **S**poofing | Can identity be faked? Is auth per-request? |
+| **T**ampering | Can data be modified in transit/storage? Integrity checks? |
+| **R**epudiation | Are actions logged with user identity? |
+| **I**nformation Disclosure | Can unauthorized data be accessed? |
+| **D**enial of Service | Resource limits? Rate limiting? |
+| **E**levation of Privilege | Can roles be escalated? Input validation on role fields? |
+
+**Phase 7: Git History Archaeology** (deep only)
+
+```bash
+# Search for previously committed secrets
+git log --all --diff-filter=D --name-only --pretty=format: -- "*.env" "*.key" "*.pem" 2>/dev/null | head -20
+git log -p --all -S "password" --since="1 year ago" -- "*.ts" "*.js" 2>/dev/null | head -50
+```
+
+**Phase 8: Report**
+
+Output severity matrix:
+
+```
+=== Security Audit ({tier}) ===
+
+CRITICAL ({count}):
+  - [A03] SQL injection in {file}:{line} — {description}
+    Fix: {remediation}
+
+HIGH ({count}):
+  ...
+
+MEDIUM ({count}):
+  ...
+
+LOW ({count}):
+  ...
+
+Summary: {total} findings ({critical} critical, {high} high, {medium} medium, {low} low)
+```
+
+**Register artifact on completion:**
+
+Confirm before writing:
+```
+AskUserQuestion("Register security-audit artifact RVW-{NNN} in state.json? (yes/no)")
+→ yes: proceed with write
+→ no: skip registration, continue to completion
+```
+
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "review"),  // RVW-NNN (security-audit reuses review type)
+  type: "review",
+  subtype: "security-audit",
+  milestone: current_milestone || null,
+  phase: target_phase || null,
+  scope: target_phase ? "phase" : "standalone",
+  path: "scratch/{YYYYMMDD}-security-audit-{tier}-{slug}",
+  status: critical_count == 0 ? "completed" : "completed_with_concerns",
+  tier: tier,                              // quick|standard|deep
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+Write findings report to the same `path` (severity matrix, file:line refs, remediation).
+</execution>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS
+CONCERNS: {count} critical findings require immediate action
+--- END STATUS ---
+```
+
+Status mapping:
+- **DONE** — No critical/high findings
+- **DONE_WITH_CONCERNS** — Critical/high findings documented with remediation
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| No critical findings | `/quality-review {phase}` |
+| Critical findings need fix | `/maestro-plan {phase} --gaps` |
+| Need deeper analysis | `/security-audit deep --scope {path}` |
+| Want dependency remediation | Fix vulnerabilities, then re-run `/security-audit` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No source files found in scope | Verify --scope path exists |
+| E002 | error | Tech stack not detected | Manually specify entry points |
+| W001 | warning | npm audit / dependency tool unavailable | Skip dependency phase, note limitation |
+| W002 | warning | Git history scan failed | Skip Phase 7, note limitation |
+| W003 | warning | Partial scan (some files inaccessible) | Report coverage gap in findings |
+</error_codes>
+
+<success_criteria>
+- [ ] Tech stack identified and entry points mapped
+- [ ] OWASP Top 10 categories all checked (tier-appropriate)
+- [ ] Dependency audit completed with CVE listing
+- [ ] Severity matrix produced with file:line references
+- [ ] Each finding includes remediation suggestion
+- [ ] Completion status block emitted
+</success_criteria>