# Cite Placement > >- - **Type:** Skill - **Install:** `agentstack add skill-kennethkhoocy-legal-scholarship-skills-cite-placement` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [kennethkhoocy](https://agentstack.voostack.com/s/kennethkhoocy) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [kennethkhoocy](https://github.com/kennethkhoocy) - **Source:** https://github.com/kennethkhoocy/legal-scholarship-skills/tree/main/plugins/legal-scholarship/skills/cite-placement ## Install ```sh agentstack add skill-kennethkhoocy-legal-scholarship-skills-cite-placement ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Citation Placement Unified router for three citation workflows. A single Tkinter launcher collects inputs and writes `run_config.json`; the `"pipeline"` value selects one of three modes, each with its own detailed workflow document. ## Modes and Routing | Mode | `pipeline` value | What it does | Workflow doc | |---|---|---|---| | Inline placement | `inline` | Places screened citations as inline `\cite{}` / `\citet{}` / `\citep{}` commands with a compiled `references.bib`. For economics, finance, and social-science journals (APA, MLA, Harvard, Chicago author-date, IEEE, Vancouver). `.tex` only. | `references/phase-details-inline.md` | | Footnote placement | `footnotes` | Places screened citations as full formatted `\footnote{}` (LaTeX) or native OOXML footnotes (Word), with one-click legal/notes style selection (Bluebook, OSCOLA, Chicago notes-bib, APA 7th, McGill) and Id./supra short-form post-processing. `.tex` or `.docx`. | `references/phase-details-footnotes.md` | | Restyle | `restyle` | Converts ALL existing footnote citations (hand-written or pipeline-placed) from one style to another. No spreadsheet required. `.tex` or `.docx`. | Restyle Pipeline section of `references/phase-details-footnotes.md` | Read the relevant workflow document at the start of each phase. ## Launcher-First Protocol When the user triggers this skill: 1. Run the launcher with a **10-minute timeout** (the user needs time to browse and configure), using the skill's known absolute directory as `[skill-dir]`, not the current working directory: ```bash python "[skill-dir]/scripts/launcher.py" ``` Call it via the Bash tool with `timeout: 600000`. 2. The unified GUI presents the file fields and options for all three modes and offers three run buttons — **Inline Placement**, **Footnote Placement**, and **Restyle** — plus a **Utilities** area (Strip All Citations; Regenerate / Reorder Cross-Refs, with or without an existing registry). On any run button the launcher validates inputs and writes `placement/run_config.json` in the **output file's parent directory**, then prints machine-readable status lines to stdout. 3. Parse the launcher's stdout: - `LAUNCHER_STATUS: success` — proceed. If missing or `cancelled`, stop. - `LAUNCHER_CONFIG_PATH: ` — the absolute path to `run_config.json`. Use this path for all subsequent phases. All paths inside the config are absolute; do not assume the config lives in the current working directory. 4. Read `run_config.json` and route on `config["pipeline"]`: - `"inline"` → run the inline placement pipeline (`references/phase-details-inline.md`). - `"footnotes"` → run the footnote placement pipeline (`references/phase-details-footnotes.md`). - `"restyle"` → run the restyle pipeline (Restyle Pipeline section of `references/phase-details-footnotes.md`). 5. **Run the selected pipeline end-to-end without asking questions or waiting for confirmation between phases.** The only pause is the Phase 4 human-in-the-loop gate in the two placement modes, and only when `auto_approve` is `false`. ### `run_config.json` shapes The config always lives at `/placement/run_config.json`. The `"pipeline"` key selects the shape: ```jsonc // inline {"pipeline": "inline", "input_format": "tex", "project_folder": "...", "input_tex": "...", "input_xlsx": "...", "output_tex": "...", "citation_style": "apa|mla|harvard|chicago_author_date|chicago_notes|ieee|vancouver", "replan": false, "auto_approve": false, "citation_mode": "selective|comprehensive", "insertion_style": "prose|simple", "verify_citations": false} // footnotes {"pipeline": "footnotes", "input_format": "tex|docx", "project_folder": "...", "input_tex": "...", "input_xlsx": "...", "output_tex": "...", "replan": false, "auto_approve": false, "citation_style": "bluebook|oscola|chicago|apa|mcgill", "citation_mode": "selective|comprehensive", "verify_citations": false} // restyle {"pipeline": "restyle", "input_format": "tex|docx", "project_folder": "...", "input_tex": "...", "input_xlsx": null, "output_tex": "...", "current_style": "...", "target_style": "..."} ``` ## Citation slots (`% CITE:`) Drafts from the `writing-article-plans` skill mark where citations belong with typed placeholder slots, and its `assemble_manuscript.py` normalizes footnote-wrapped slots before handoff. A slot is a `% CITE:` LaTeX comment carrying a typed hint (e.g. `% CITE: meta-analysis on Y`). Slots are a `.tex` convention only — footnotes-mode `.docx` input has no slot support. **Core rule (both placement modes).** If the input manuscript contains `% CITE:` slots, every slot MUST end the run either filled or explicitly reported as unfilled with a reason. Silent slot survival is a pipeline failure. Slots are author-declared citation demands, so `citation_mode: "selective"` governs only free placements and never skips a slot. Three slot forms reach this skill: 1. **Bare comment** — `% CITE: ` on its own line or at the end of a line. 2. **Footnote-wrapped, two-line** (`\footnote{%` / `% CITE: ` / `}`) — the normal post-assembly form (brace-safe). 3. **Footnote-wrapped, one-line** — `\footnote{% CITE: }`; compile-unsafe (the `%` comments out the closing brace). Recognize it and recommend running writing-article-plans' `assemble_manuscript.py` first. `% RESULT:` slots belong to a different pipeline and MUST never be touched or removed. The contract lives in the phase docs: Phase 1 enumerates slots into `citation_slots`, Phase 3a fills each or defers it to `unfilled_slots`, Phase 4 reports the tally, and Phase 5 executes the replacements and runs a deterministic `grep` closure check. See `references/phase-details-inline.md` and `references/phase-details-footnotes.md`. ## Inline Mode — Phase Overview (5 phases) Detailed instructions: `references/phase-details-inline.md`. - **Phase 1 — Manuscript Mapping.** Read the `.tex`; produce `placement/section_map.md` and `placement/existing_citations.json`. Detect the citation package (`natbib` → `\citet`/`\citep`; `biblatex` → `\textcite`/`\parencite`; else basic `\cite`) and the bibliography backend (`bibtex`/`biber`). **Cached** unless `replan` is `true`. Read-only. - **Phase 1.5 — Existing Citation Verification (optional).** Gated on `verify_citations`. Flags dangling `\cite{}` keys, hallucinated `.bib` entries, and spreadsheet overlaps into `placement/audit_report.json`. - **Phase 2 — Citation Ingestion.** `scripts/core/ingest_citations.py` turns the `.xlsx` into `citations.json` + `references_new.bib`. Deterministic, no LLM. - **Phase 3 — Placement Planning (3a → 3b → 3c).** 3a assigns each citation to all supporting sections (multi-placement is normal); 3b spawns one general-purpose sub-agent per section to draft anchors and cite commands, keyed to `insertion_style` (`prose` default — Types 1/2/3 with sentence rewriting; `simple` — parenthetical-only, no rewriting); 3c consolidates into `placement/placement_plan.md`. **Cached / incremental**: with `replan: false`, only cite keys absent from the `planned_keys` header trigger new planning. - **Phase 4 — HITL Review.** Always print the plan. Pause for corrections when `auto_approve` is `false`; otherwise continue immediately. - **Phase 5 — Execution.** Copy the `.tex` to a versioned output, insert cites (parenthetical = insert after anchor; prose/textual = replace anchor), merge `references_new.bib`, ensure `\bibliographystyle{}`/`\bibliography{}` (or `\addbibresource`/`\printbibliography` for `biblatex`), then compile with `pdflatex` + `bibtex`/`biber` + two more `pdflatex` passes. ## Footnote Mode — Phase Overview (6 phases) Detailed instructions: `references/phase-details-footnotes.md`. Accepts `.tex` (LaTeX `\footnote{}`, compiled with `xelatex`) or `.docx` (native OOXML footnotes via `scripts/core/docx_support/`); for `.docx`, skip every LaTeX-specific step (no `xelatex`, no `%CITE-PLACED`, no `\bibliography{}`). - **Phase 1 — Manuscript Mapping.** Produce `placement/section_map.md` and `placement/existing_footnotes.json`, classifying each footnote (`article`/`book`/`working_paper`/`case`/`legislation`/`cross_reference`/`discursive`/`mixed`). **Cached** unless `replan`. - **Phase 1.5 — Existing Citation Audit (optional).** Gated on `verify_citations`; verification cascade (OpenAlex → CrossRef → Google Scholar) into `placement/audit_report.json`. - **Phase 2 — Citation Ingestion.** `scripts/core/ingest_citations.py` → `citations.json` + `references_new.bib`. Deterministic. - **Phase 3 — Placement Planning (3a → 3b → 3c).** Style-specific rules are read from `references/styles/.md` and injected into the 3b sub-agent prompts; every placement carries the **full** citation string (Phase 6 handles repeats). 3c merges same-anchor placements into single multi-citation footnotes. **Cached / incremental** on the `planned_keys` header. - **Phase 4 — HITL Review.** Pause when `auto_approve` is `false`. - **Phase 5 — Execution.** Copy the manuscript; insert each `\footnote{` with an invisible `%CITE-PLACED` marker immediately after the opening brace; apply Phase 1.5 audit fixes; tag any pre-existing footnotes with `%CITE-PLACED`; run `merge_adjacent_footnotes.py`; then Phase 6; then `xelatex` (one pass, no `bibtex`/`biber`). - **Phase 6 — Short-Form Post-Processing.** `short_form.py` converts repeat citations to the style's short form (Id./ibid/supra/shortened title/author-date) and writes `placement/footnote_registry.json` for later cross-reference reordering. Runs automatically after Phase 5; compile `xelatex` twice to settle footnote numbers. ### `%CITE-PLACED` marker rule Every `\footnote{}` in a `.tex` output carries `%CITE-PLACED` immediately after the opening brace (a LaTeX comment `pdflatex` ignores, so the PDF is unchanged). The marker lets `strip_citations.py` cleanly remove all pipeline footnotes for a clean re-run, and it is preserved through merge and short-form rewrites. ## Restyle Mode — Overview Detailed instructions: Restyle Pipeline section of `references/phase-details-footnotes.md`. Converts every existing footnote citation from `current_style` to `target_style`, correcting Id./ibid/supra cross-references and symbol-footnote numbering. The `.tex` path spawns one sub-agent per section and finishes with `merge_adjacent_footnotes.py` + `short_form.py`; the `.docx` path extracts footnotes via `scripts/core/docx_support/`, restyles them, and writes back via `replace_footnote_text`. Standalone drivers: `scripts/docx_restyle.py` and `scripts/tex_restyle.py` (each takes `--config placement/run_config.json`). Case citations, legislation, and discursive footnotes pass through unchanged. ## Utilities The launcher's Utilities area (and the corresponding scripts) support maintenance outside a full run: - **Strip All Citations** — `strip_citations.py` removes every `%CITE-PLACED` footnote, yielding a clean manuscript for a from-scratch re-run. - **Regenerate / Reorder Cross-Refs** — `reorder_crossrefs.py` reverses all short forms to full citations and re-applies them with correct footnote numbering after manual footnotes shift the numbering. Uses `placement/footnote_registry.json` (created by Phase 6); when the registry is absent it reconstructs from the current full citations. - **Migrate markers** — `migrate_markers.py` retroactively adds `%CITE-PLACED` to footnotes in manuscripts produced before the marker convention. ## Commands `[skill-dir]` is the absolute path to this skill's directory. All paths shown as `placement/...` are relative to the output file's parent directory. | Command | Purpose | Invocation | |---|---|---| | Launcher | Collect inputs, write `run_config.json` | `python "[skill-dir]/scripts/launcher.py"` (Bash `timeout: 600000`) | | Ingest | `.xlsx` → `citations.json` + `references_new.bib` (deterministic) | `python "[skill-dir]/scripts/core/ingest_citations.py" --input citations.xlsx --output-json citations.json --output-bib references_new.bib [--existing-bib references.bib] [--min-score N]` | | Verify (inline) | Audit existing `\cite{}` keys vs `.bib` + APIs | `python "[skill-dir]/scripts/core/verify_citations.py" --mode inline --citations placement/existing_citations.json --bib references.bib --output placement/audit_report.json [--spreadsheet cites.xlsx]` | | Verify (footnotes) | Audit existing footnote citations vs APIs | `python "[skill-dir]/scripts/core/verify_citations.py" --mode footnotes --footnotes placement/existing_footnotes.json --output placement/audit_report.json [--spreadsheet cites.xlsx]` | | Merge adjacent footnotes | Combine adjacent `\footnote{}...\footnote{}` (Phase 5 post-proc) | `python "[skill-dir]/scripts/merge_adjacent_footnotes.py" --input OUT.tex --output OUT.tex --style --skill-dir "[skill-dir]"` | | Short form | Style-aware Id./supra/ibid substitution (Phase 6) | `python "[skill-dir]/scripts/short_form.py" --input OUT.tex --output OUT.tex --style --skill-dir "[skill-dir]" [--plan-dir placement/]` | | Reorder cross-refs | Fix supra/Id. after manual footnote edits | `python "[skill-dir]/scripts/reorder_crossrefs.py" --input OUT.tex [--plan-dir placement/]` | | Strip citations | Remove all `%CITE-PLACED` footnotes | `python "[skill-dir]/scripts/strip_citations.py" input.tex [output.tex]` | | Migrate markers | Add `%CITE-PLACED` to legacy footnotes | `python "[skill-dir]/scripts/migrate_markers.py" input.tex [output.tex]` | | Restyle (`.docx`) | Standalone restyle driver | `python "[skill-dir]/scripts/docx_restyle.py" --config placement/run_config.json` | | Restyle (`.tex`) | Standalone restyle driver | `python "[skill-dir]/scripts/tex_restyle.py" --config placement/run_config.json` | The verification report schema is unchanged from the source pipelines: inline mode reports dangling references, per-`.bib`-entry verification, and spreadsheet overlaps; footnotes mode reports per-citation verification status, Bluebook format issues with corrected strings, and spreadsheet overlaps. ## Inline vs. Footnote Mode The two placement modes differ in output form, compilation, and style set: | Aspect | Inline mode | Footnote mode | |---|---|---| | Citation command | `\cite{key}`, `\citep{key}`, `\citet{key}` | `\footnote{Full formatted citation}` (or OOXML footnote) | | `.bib` file | **Essential** — compiled by LaTeX into the bibliography | Vestigial record only; not compiled | | Compilation | `pdflatex` + `bibtex`/`biber` | `xelatex` only (footnotes are self-contained) | | Citation styles | APA, MLA, Harvard, Chicago author-date, IEEE, Vancouver | Bluebook, OSCOLA, Chicago notes-bib, APA 7th, McGill | | Short forms (Id./supra) | Not applicable — the bibliography style handles repeats | Phase 6 post-processing (`short_form.py`) | | Phase count | 5 phases (1–5) | 6 phases (1–6) | | Input format | `.tex` only | `.tex` or `.docx` | Chicago **notes-bib** and legal styles belong to footnote mode; the inline mode's `chicago_notes` option warns and points to footnote mode instead. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [kennethkhoocy](https://github.com/kennethkhoocy) - **Source:** [kennethkhoocy/legal-scholarship-skills](https://github.com/kennethkhoocy/legal-scholarship-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-kennethkhoocy-legal-scholarship-skills-cite-placement - Seller: https://agentstack.voostack.com/s/kennethkhoocy - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.