From productivity-forge
Core orchestration loop for the verification-forge plugin. Orchestrate phased document editing, data analysis, and knowledge work using sub-agents for research, drafting, verification, and review — with integrity gates between phases. Use whenever the task involves multi-phase document restructuring, data-driven content editing, grant or manuscript revision, spreadsheet analysis with narrative output, cross-document consistency work, or any productivity task where claims must be verified against source data and changes must be auditable. Triggers on: multi-section document edits, "restructure this grant/paper/report," "update these numbers throughout," "verify these claims against the data," "consolidate scattered content," "rewrite this section with new data," tracked-change workflows, or any productivity task requiring phased implementation with quality gates. Supersedes ad-hoc document editing when the work spans multiple sections, involves data verification, or requires review before finalizing.
npx claudepluginhub ildunari/kosta-plugins --plugin productivity-forgeThis skill uses the workspace's default tool permissions.
Orchestrate phased productivity work using sub-agents for research, drafting, verification, and review — with integrity gates between phases. The orchestrator delegates, coordinates, verifies, and fixes. Sub-agents execute focused tasks and report back with evidence.
FEEDBACK.mdreferences/education-writing.mdreferences/engineering-writing.mdreferences/financial-writing.mdreferences/journalism-writing.mdreferences/legal-writing.mdreferences/medical-writing.mdreferences/policy-writing.mdreferences/review-dimensions.mdreferences/scientific-writing.mdreferences/subagent-orchestration.mdreferences/tool-inventory.mdreferences/tool-patterns.mdProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Analyzes competition with Porter's Five Forces, Blue Ocean Strategy, and positioning maps to identify differentiation opportunities and market positioning for startups and pitches.
Orchestrate phased productivity work using sub-agents for research, drafting, verification, and review — with integrity gates between phases. The orchestrator delegates, coordinates, verifies, and fixes. Sub-agents execute focused tasks and report back with evidence.
This skill exists because productivity work — grants, manuscripts, reports, spreadsheets, lab documentation — has a verification problem that code doesn't. Code has compilers, test suites, and debuggers. Documents have nothing. A wrong number in a grant, a lost citation, a stale claim repeated in three sections — these failures are invisible until a reviewer catches them. The agentic loop compensates by building verification into every phase: no content is written without verified source data, no edit is accepted without a post-apply integrity check, and no phase is complete without independent review.
Read FEEDBACK.md before every use to apply lessons from prior sessions. After completing a task, note anything that didn't work well and log it in FEEDBACK.md with a date, category tag, and one actionable observation.
Load reference files only when their content is needed, not at the start of the session.
| Reference file | When to load |
|---|---|
FEEDBACK.md | Before every use — always |
references/subagent-orchestration.md | Before the first sub-agent dispatch in a session |
references/review-dimensions.md | Before the Dual Review step (step 7) — read only the section for the current domain plus Language Review |
references/tool-patterns.md | When a tool operation fails or behaves unexpectedly |
references/tool-inventory.md | During the "Before Starting" inventory step, only if the user hasn't specified their tools |
references/scientific-writing.md | When the domain is scientific writing (grants, papers, abstracts) |
| Other domain references | When the domain matches (see Domain Routing) |
Work from this file (SKILL.md) alone until a specific step requires reference material.
Use this skill when the task has three or more of these characteristics:
For single-paragraph edits, simple formatting, or tasks without data verification needs, just do the work directly — this skill adds overhead that isn't justified for small tasks.
The verification-forge plugin routes sub-agent work to the appropriate model tier based on the cognitive demands of the task:
Opus — for tasks requiring deep analytical reasoning, source-level verification, and domain expertise:
Sonnet — for tasks requiring fluent generation, pattern matching, and style-focused evaluation:
When dispatching sub-agents, annotate the model tier in the prompt contract so the routing layer can assign the correct model. If model routing is not available in the current environment, all sub-agents default to the orchestrator's model.
If the task scope is unclear, interview the user:
"I can start, but I'll produce better results with more context. Can I ask a few questions about the document, the data sources, and what 'done' looks like?"
Gather:
If the user already provided detailed context (prior conversation, attached files, existing plan), extract answers from what's available and confirm before proceeding.
Research → Source Verify → [Structure Plan] → Draft → Apply Gate → Integrity Gate → Dual Review → Fix → Save + Document
│ │
└─── fail: diagnose & retry ◄──────────────┘
Each step in detail:
Read the document, the data sources, and any reference materials. Build a complete picture of:
Dispatch an Explore sub-agent for broad research when the document is large or unfamiliar. For focused tasks where you already have context, do this inline.
Output: A structured inventory — what exists, what's wrong, what's missing, what the canonical values are.
Before writing any content, verify every value you plan to use. Source verification runs before every drafting step when the content references data values, calculations, or quantitative claims.
Dispatch a verification sub-agent to:
The orchestrator reviews the Claim Ledger before proceeding to drafting. If any value is uncertain, ambiguous, or inconsistent between sources, resolve it now — not during drafting.
This step also runs after implementation as a review gate (see Integrity Gate below). Source verification bookends the process.
Every phase that touches factual content must produce or update a Claim Ledger — a persistent artifact that tracks each quantitative or verifiable statement from source to final text. The ledger prevents value drift across phases, makes the workflow resumable after interruption, and catches the subtle errors that survive spot-checking (transposed digits, stale values, silent unit changes).
Standard Schema (moderate-stakes, <10 claims):
| Field | Description |
|---|---|
| Claim ID | Unique identifier (e.g., C-01) |
| Claim Text | Statement as it appears in the draft |
| Raw Value | Original value from source |
| Display Value | Value as rendered in output (with rounding, units) |
| Source File | File path or document name |
| Source Location | Page, table, figure, or cell reference |
| Citation(s) | Formal citation(s) supporting the claim |
| Verification Status | verified / flagged / pending |
Extended Schema (high-stakes quantitative, >10 claims, or compliance-sensitive) adds:
| Field | Description |
|---|---|
| Unit | Measurement unit for the value |
| Condition / Timepoint | Experimental context (e.g., "A(+/+), 96h cumulative") |
| Formula / Transform | How the display value was derived from raw |
| Rounding Rule | Rule applied (e.g., "nearest 0.1M") |
| Claim Type | direct / derived / inferential / editorial |
| Dependent Locations | Other documents or sections that reference this claim |
| Notes | Discrepancies, caveats, reviewer flags |
Rules:
Derived values — fold-changes, percentages, ratios, normalized metrics, unit conversions, rankings — are the most likely site of sophisticated hallucination. They sound analytically credible, so neither the writer nor the reviewer tends to question them. The ledger must make every derivation auditable.
For each derived claim, record:
| Field | Description |
|---|---|
| Formula Used | Exact operation (e.g., A(+/+) ÷ B(+/-)) |
| Raw Inputs | Values and their Claim IDs (e.g., C-03, C-04) |
| Computed Result | Unrounded output of the formula |
| Display Value | Final value shown in text |
| Rounding Rule | Rule applied to reach display value |
Rules:
source-stated and log the source location — direct source confirmation counts as verification without recomputation.| Tier | Scope | When to Use |
|---|---|---|
| Tier 1 — Exploratory | Spot-check 3-5 representative values | Discovery, research inventory, or internal notes that will not appear directly in any output |
| Tier 2 — Standard | Verify 100% of claims in changed text | Single-section quantitative edits with fewer than 10 claims |
| Tier 3 — High-Stakes | Verify 100% of changed claims + run a dependency sweep across all declared files | Multi-section edits, >10 claims, compliance-sensitive content, or cross-document work |
Rules:
Required when a phase involves moving, merging, splitting, or consolidating content across sections.
Before any Draft step, produce a Structure Plan:
| Current location | Target location | Action | Dependencies | Rationale |
|---|---|---|---|---|
| Section / paragraph ref | Section / paragraph ref | keep / move / split / delete / rewrite | Citations, figures, comments affected | Why this move serves the phase goal |
Rule: The Draft step cannot begin until the orchestrator reviews and approves the Structure Plan. This is the productivity equivalent of "test before code" — it forces structural decisions before prose work starts, preventing costly mid-draft reorganizations.
Dispatch a drafting sub-agent with:
The sub-agent returns the drafted text. The orchestrator reviews it against the Claim Ledger before applying.
Sub-agent prompt contract for drafting (include all of these):
See references/subagent-orchestration.md for detailed prompt contracts and examples.
Apply the drafted content to the document using available tools. After applying:
If the tool operation fails or produces unexpected results, diagnose before retrying. Load references/tool-patterns.md for known issues and workarounds.
General principles for tool operations:
After applying changes, run an integrity check. This is the productivity equivalent of "run the tests."
For document editing:
For spreadsheet work:
For any domain:
verified in the ledgerDispatch a verification sub-agent for thorough checks. The sub-agent should have access to the source files and the document, and should report: what it checked, what passed, what failed, and exact quotes of any issues.
Scripts (optional accelerators): If scripts/ is available, the following automate common integrity checks:
scripts/stale_value_finder.py — searches multiple files for deprecated valuesscripts/citation_integrity_check.py — diffs citations between document versionsscripts/cross_doc_consistency_checker.py — compares metrics across documentsscripts/doc_structure_audit.py — validates heading hierarchy and section completenessTwo independent reviews, run in parallel when possible. Load references/review-dimensions.md before this step — read only the section for the current domain plus the Language Review section.
Plugin note: In the verification-forge plugin, this step dispatches to the reviewer-gate skill, which manages 13 independent reviewer agents across domain accuracy, language quality, citation integrity, structural compliance, and more. See
reviewer-gate/SKILL.mdfor the full reviewer roster, dispatch protocol, severity calibration, and finding consolidation logic. The dimensions below remain the baseline checklist; the reviewer-gate expands each into a dedicated agent with its own prompt contract and evidence requirements.
Domain Review — checks accuracy and compliance:
Language Review — checks tone and naturalness:
Sub-agent prompt contract for reviewers (include all of these):
The orchestrator reads both review reports and fixes P0 and P1 issues directly. Do not delegate fixes — the orchestrator has seen both reviews and has the full context.
After fixing, loop back to the Apply Gate (step 5) to verify fixes didn't introduce new problems.
P2 items are fixed if the effort is trivial. P3 items are noted for the user but not fixed unless requested.
If a fix can't be applied programmatically (e.g., requires GUI interaction, or the tool doesn't support the operation):
Once all gates pass and reviews are clean:
Before starting any phase, declare:
Phase: [name]
Goal: [one sentence]
Scope: [sections / paragraphs / cells / files]
Estimated size: [small (1-3 items) / medium (4-10) / large (11+) — split large]
Risk tier: [exploratory / standard / high-stakes]
Target structure: [outline or movement map, if restructuring]
Source data: [canonical files to verify against]
Source precedence: [which file wins if sources disagree]
Claim ledger: [path or "new"]
Derived calculations: [list or "none"]
Stale-claim search scope: [which docs/sections to sweep]
Dependent files: [other documents that may contain the same claims]
Checkpoint: [backup path before destructive operations]
Domain reviewer: [scientific / legal / financial / general]
Language reviewer: [tone target — match existing, formal, accessible]
Outputs: [tracked doc / clean doc / change log / ledger update]
Page/word budget: [limit, if applicable]
Phases estimated as large (11+ items) must be split into smaller phases before work begins. The Integrity Gate must sweep all files listed in Dependent files, not only the primary output document.
Not every edit needs the full 16-field phase declaration. For standard-risk work (a single section, fewer than 5 claims, no cross-document dependencies, no restructuring), use the compact declaration:
Phase: [name]
Goal: [one sentence]
Scope: [what to touch]
Source data: [canonical file(s)]
Risk tier: Standard
The compact path still requires Source Verify, Apply Gate, Integrity Gate, and Save + Document — it just uses lighter artifacts. Claim IDs are optional at this scale; the orchestrator tracks values inline. If the work grows beyond the compact scope (more claims appear, cross-document dependencies emerge, restructuring becomes necessary), upgrade to the full declaration immediately rather than patching the compact one.
If any of the following are true, stop the current workflow and reassess before proceeding:
Use sub-agents when:
Work inline (as orchestrator) when:
Orchestrator verification protocol: When using sub-agents, follow the verification protocols in references/subagent-orchestration.md. The core principle: verify values a sub-agent reports by reading the source file directly — sub-agents can fabricate or misread values, so independent verification catches errors before they propagate.
Context budget guidance: The orchestrator typically runs with a large context window (~1M tokens) and can hold full session context. Sub-agents have smaller windows (200-400K tokens) and need focused, self-contained task packets. When dispatching sub-agents: include only the files and context needed for their specific task, prefer structured output formats that are quick to parse, and run independent tasks in parallel to save time.
When something goes wrong:
Three principles for error handling: (1) document every failed operation before moving on, (2) try a different approach rather than repeating the same one, and (3) read the result after every operation to confirm success.
Long editing sessions can exhaust the context window. To preserve state across a long session:
Different domains need different gate criteria and review dimensions. Load the appropriate reference file based on the work type:
| Domain | Reference | Key gates |
|---|---|---|
| Scientific writing (grants, papers) | references/scientific-writing.md | Data accuracy, citation integrity, methodology consistency, variance reporting |
| Legal (contracts, briefs, filings) | references/legal-writing.md | Defined terms consistency, obligation precision, Bluebook citations, privilege protection |
| Financial (10-K, budgets, audits) | references/financial-writing.md | GAAP compliance, formula integrity, reconciliation, audit trail, SEC formatting |
| Medical (protocols, CSRs, regulatory) | references/medical-writing.md | CONSORT/STROBE compliance, adverse event reporting, IRB alignment, HIPAA |
| Engineering (specs, test reports, safety) | references/engineering-writing.md | Requirements traceability, units consistency, tolerance notation, standards compliance |
| Policy (white papers, RIAs, legislation) | references/policy-writing.md | Source attribution, stakeholder framing, data provenance, public comment compliance |
| Education (curricula, rubrics, accreditation) | references/education-writing.md | Learning objectives alignment, Bloom's taxonomy, assessment validity, UDL accessibility |
| Journalism (investigations, fact-checks, data) | references/journalism-writing.md | Source verification (2+ independent), quote accuracy, defamation risk, correction protocols |
Other domains not listed above should apply the general verification and review principles from the Core Loop. The review dimensions in references/review-dimensions.md cover language quality for all domains. Use the domain-router skill to auto-detect and activate the appropriate domain. If you encounter a recurring domain not covered here, note it in FEEDBACK.md so a dedicated reference file can be created.
This skill is tool-agnostic — it describes what operations to perform, not which specific tools to use. However, the orchestrator should:
references/tool-patterns.md when a tool operation fails or behaves unexpectedlySee references/tool-inventory.md for a catalog of common productivity tools and when each is useful. Tool names and availability change over time — use the catalog as a starting point for discovery, not as a definitive list.
The scripts/ directory contains Python scripts that automate common verification and integrity tasks. These are optional — the orchestrator can perform equivalent checks manually — but they are faster and more deterministic for repetitive auditing.
| Script | Purpose | Used in |
|---|---|---|
scripts/claim_ledger.py | Create, update, and verify claim ledgers from source files + documents | Source Verify, Integrity Gate |
scripts/stale_value_finder.py | Search multiple files for deprecated values (exact + alternate forms) | Integrity Gate |
scripts/citation_integrity_check.py | Diff citations between before/after document versions | After Apply Gate |
scripts/cross_doc_consistency_checker.py | Compare metrics across multiple documents | Integrity Gate (multi-doc phases) |
scripts/doc_structure_audit.py | Validate heading hierarchy, section completeness, word counts | Before Dual Review |
Dependencies: python-docx, openpyxl, re, json, csv (standard library). Scripts run standalone and accept file paths as arguments.
If scripts are not available: perform equivalent checks manually or via sub-agent. The scripts accelerate verification but are not required for the loop to function.
Escalate to the user when: