Research Projects — self-contained, git-backed research entities with prescribed layout

[jeonghun-jj-lee]

Research Projects — self-contained, git-backed research entities with prescribed layout

Density: PRD. This is a parent design-of-record. Decompose into sub-issues via break-into-subissues before implementation.

Important

Problem: Amicode has no concept of a research project — a bounded investigation from hypothesis to paper. Researchers organically create git repos with no prescribed structure, manifest, or autoresearch integration. Problem workspaces are domain-pack-specific and nearly unused. The existing Project concept is a workstation directory, not a research endeavor.

Approach: Introduce Research Project as a structured flavor of Project — a self-contained, git-backed research entity with a prescribed directory layout, project-specific skills, a gated paper-writing workflow, and a linear lifecycle. Identified by project.toml. The existing git-repo model continues as Dev Project. Both appear in the workspace-backed project selector (grouped, visually distinct). The autoresearch director reads the research project directory as its entire context. Armonia is repositioned as a future coordination layer.

Approaches Considered:

• (A) Umbrella with two flavors (chosen) — "Project" is the umbrella; Research and Dev are the two types. No breaking glossary change.
• (B) Full redefine — "Project" means only research entities. Breaks the glossary.
• (C) New "Study" entity — No glossary change but two overlapping concepts.

Scope: Entity definition, directory layout (including skills/), manifest schema, workspace-backed project selector, creation/import flows, skill auto-loading, paper-writing skill with authorship gates, autoresearch integration, glossary updates. Does NOT implement the Armonia coordination layer, vault promotion, per-session skill scoping, or Armonia sidebar/service changes (Armonia's current infrastructure is untouched; only CONTEXT.md gains the Research/Dev flavor definitions).

Assumptions: ProjectTable can recognize project.toml. Git required for Research Project identity (Dev Projects retain existing behavior, including non-git directories). The autoresearch director is updated to read project context.

Cross-repo dependencies: Skill auto-loading and session binding touch the opencode engine (ProjectTable, prepareOpencodeProject(), AGENTS.md compilation), which ships on its own release cadence via the vendored fork. These require coordinated changes across harmoniqs/amicode and harmoniqs/opencode.

Acceptance Criteria

Entity & layout

• project.toml schema defined: schema_version, name, slug, question, status (proposing/designing/running/analyzing/writing/complete), created, tags[], authors (lead + collaborators[]), venue (name + deadline), domain_pack (metadata-only; does not gate skill loading or substrate checks), related_projects[], doi
• Prescribed directory scaffolded on creation:
  • scripts/ with README.md and testbed/
  • data/{raw,processed,plots}
  • analysis/
  • paper/ as standalone LaTeX (outline.md, main.tex, references.bib, figures/, supplementary/, latexmkrc, .gitignore)
  • ledger/{hypotheses,observations,literature,campaigns}
  • config/ with optional system.toml, lab.toml
  • skills/ for project-specific agent skills

Project selector (adapted PromptProjectSelector)

• Un-gate in Amicode webview (remove !inAmicode() guard)
• Persistent chip below composer, always visible
• Shows workspace folders, typed by project.toml presence (Research vs Dev)
• Grouped dropdown: "Research" section (with status badges) and "Development" section
• "New project" action — research project creation flow
• "Open project" action — directory picker, auto-detects type, adds to workspace
• Add-only: no removal in selector; removal via VS Code native "Remove Folder from Workspace"
• Adding a project in the selector adds it to the VS Code workspace

Creation & import

• Three creation surfaces: Amico interview, CLI (amico project create), selector "New project"
• CLI contract: amico project create <name> [--path <dir>] [--domain <pack>] [--venue <name>] [--deadline <date>]. Defaults: path = ~/projects/<slug>, domain = none, venue = none. Creates dir, git init, scaffolds layout, writes project.toml, adds to workspace.
• Import flow: amico project import [<dir>] (default: .) scaffolds missing dirs in-place without moving or overwriting existing files; adds project.toml; if scripts/ exists but has no testbed/, creates testbed/ inside it. Also available via chat ("make this a research project").

Skill auto-loading

• On workspace folder change, scan each folder for project.toml; add each research project's skills/ as a skill source
• Trigger prepareOpencodeProject() re-run on workspace change (project added/removed)
• Project skills merged with shadow priority: project > custom > workspace > shipped
• AGENTS.md skill index recompiled to include project skills (source = "project")
• All project skills from all open projects visible to all sessions (per-session scoping is future work)

Paper-writing workflow

• paper/outline.md scaffolded at project creation with venue-aware template (standard sections, guiding comments, frontmatter with status: draft)
• Shipped paper-writer skill with SKILL.md implementing the gated workflow
• paper-writer skill capabilities listed in SKILL.md: sentence expansion from outline, data citation with inline results, figure placement and captioning, bibliography management (DOI lookup, BibTeX), outline gap detection, proofreading, equation formatting
• Hard gate (code-enforced): agent tool/skill refuses to write to paper/main.tex when paper/outline.md is absent or has status: draft
• Hard gate (code-enforced): section-by-section approval — agent formats one section at a time; approved sections tracked in outline frontmatter (sections_approved[]); the skill does not proceed to the next section until the current one is approved
• Soft gates (skill instructions): paper-writer SKILL.md includes provenance rule (paragraphs trace to outline bullets), forbidden-actions list (no novel conclusions, no result interpretation, no abstract generation, no emphasis selection), and data-grounding rule (quantitative claims cite files in data/). These are LLM instructions enforced probabilistically, not code gates.
• paper-writer skill overridable per-project via skills/paper-writer/SKILL.md
• Venue-aware outline templates: PRL (compressed, 4-page), PRX Quantum (full), arXiv (general), minimal (no venue)

Autoresearch integration

• Director reads project directory as context: project.toml, ledger/, data/, scripts/, config/
• Campaign ledgers written to ledger/campaigns/campaign-<YYYYMMDD>-<slug>.md

Infrastructure

• Multi-root workspace support; sessions bind to project selected in selector chip at creation
• Lifecycle tracking: status in project.toml, advanceable by user or Amico
• paper/ independently buildable by latexmk -pdf main.tex
• CONTEXT.md updated: Project gains Research/Dev flavor definitions; Armonia definition unchanged (coordination-layer repositioning is deferred to the Armonia coordination layer issue)
• ADR 0012 committed

Key Decisions

Decision	Rationale
Project as umbrella (Research + Dev)	No breaking glossary change; researchers get "project"; developers keep existing behavior
Git-backed required	Stable identity, versioning, collaboration
Anywhere on disk	Maximum flexibility for all users
Fully prescribed layout	Amico can navigate any project; autoresearch context is deterministic
Self-contained (data-local)	Portable: clone = complete research record
paper/ as standalone LaTeX	Independent latexmk build; file-watcher gives live rendering
ledger/ with four subdirectories	hypotheses / observations / literature / campaigns — complementary knowledge layers
campaigns/ not sessions/	"Session" = one agent conversation; "Campaign" = one autoresearch run
scripts/testbed/	Separates what you run (experiments) from where it runs (hardware/sim)
skills/ for project-specific agent skills	Projects can ship custom capabilities; auto-loaded on workspace change
Skill shadow: project > custom > workspace > shipped	Projects can customize shipped skills by name
Workspace-backed selector	Selector shows workspace folders; adding = workspace add; no separate registry
Add-only selector	Removal via VS Code native UI, not the selector
Adapt existing PromptProjectSelector	595 lines of working code; un-gate and enrich
Explicit session binding via selector chip	User chooses project at session creation; immutable after
Outline-first gate for paper writing	User drives the intellectual content; agent is typesetter, not co-author
Section-by-section paper approval	User reviews each transformation; no bulk "write the whole paper"
Shipped paper-writer skill, overridable	Default gates for responsible use; projects can customize
Venue-aware outline template at creation	Guides the user toward the right structure from day one
Armonia repositioned (not retired)	Future coordination layer; today = infrastructure
Problem workspaces omitted	Nearly unused; domain-pack-specific; autoresearch ignores them
Optional vault promotion	Standalone-first; vault is an enhancement

Data Contracts

project.toml

schema_version = 1

[project]
name = "CZ Speed Limit on Fixed-Frequency Transmons"
slug = "cz-speed-limit"
question = "What is the minimum gate time for a CZ at F > 0.9999?"
status = "running"
created = 2026-08-31
tags = ["transmon", "cz", "speed-limit"]

[project.authors]
lead = "JJ Lee"
collaborators = ["Aaron Trowbridge", "Logan Mayfield"]

[project.venue]
name = "Physical Review Letters"
deadline = 2027-03-15

[project.domain_pack]          # metadata-only; does not gate skill loading or substrate checks
name = "quantum-control"

[project.links]
related_projects = ["x-gate-transmon", "fluxonium-speed-limit"]
doi = ""

Prescribed directory tree

<project>/
  project.toml              # manifest: identity, status, metadata
  README.md                 # human-readable research overview
  .gitignore                # large data files, LaTeX build artifacts

  scripts/                  # experiment scripts
    README.md               # documents experiments and how to run them
    testbed/                # hardware interface OR simulation gym environment

  data/                     # all data artifacts
    raw/                    # direct output from runs
    processed/              # derived data (aggregated, cleaned, transformed)
    plots/                  # generated visualizations

  analysis/                 # analysis code (post-processing, comparison, notebooks)

  paper/                    # the deliverable (standalone LaTeX project)
    outline.md              # user's detailed outline (gate for paper writing)
    main.tex                # paper entry point
    references.bib          # bibliography
    figures/                # publication-quality figures
    supplementary/          # supplementary materials
    latexmkrc               # build configuration
    .gitignore              # LaTeX build artifacts

  ledger/                   # research knowledge record
    hypotheses/             # hypothesis notes (questions being tested)
    observations/           # experiment observations and findings
    literature/             # literature review and paper annotations
    campaigns/              # autoresearch campaign execution records (9-section format)

  config/                   # project-specific configuration
    system.toml             # (optional) system model parameters
    lab.toml                # (optional) lab/hardware config

  skills/                   # project-specific agent skills (auto-loaded into skill roots)

paper/outline.md frontmatter

---
status: draft | finalized
last_reviewed: 2026-09-15
sections_approved: []
---

Skill merge priority

project (from <project>/skills/)
  > custom (from skill-providers.json)
    > workspace (from .opencode/skills/)
      > shipped (library + package roots)

Project selector data shape (extended)

interface ProjectSelectorItem {
  name: string
  id: string
  worktree: string
  type: "research" | "dev"
  // Research-only:
  status?: "proposing" | "designing" | "running" | "analyzing" | "writing" | "complete"
  question?: string
  domainPack?: string
  icon?: { color?: string; url?: string }
}

Constraints & Invariants

• project.toml at root = Research Project; git repo without = Dev Project
• Research Projects must be git repositories; Dev Projects retain existing behavior (any directory, git optional)
• paper/ independently buildable by latexmk
• data/raw/ may contain large binaries; .gitignore templates include LFS patterns
• Works standalone without vault, armonia, or external state
• ~/.amico/ continues to hold global infrastructure
• Session binding is explicit (selector chip) and immutable
• Dev projects retain existing behavior unchanged
• Known intermediate state: project skills are available to ALL sessions when the project is in the workspace, regardless of session binding. A session bound to Project A can invoke Project B's skills. Per-session skill scoping requires opencode engine changes and is tracked as a separate issue.
• Multi-project skill collision: first project in workspace folder order wins
• Project skills can shadow any shipped skill by name (including shipped infrastructure skills); a warning is logged when shadowing occurs
• The paper-writer skill's outline-first gate is code-enforced; behavioral gates (provenance, forbidden actions) are skill instructions
• The abstract must be user-authored — the agent does not generate it

Prior Art

• Issue Seamless armonia migration — expand bootstrap + migration scripts, add retirement script #386 (armonia directory layout)
• ADR 0008 (autoresearch identity / domain pack boundary)
• ADR 0010 (install path contract)
• ADR 0011 (harness contract)
• PromptProjectSelector (existing 595-line component, hidden behind !inAmicode())
• opencode ProjectTable, SkillV2.Service, prepareOpencodeProject()
• diraq-esr-demo, fluxonium-demo (organic research repos)
• Director-core 9-section campaign ledger format

Source

Brainstorming + grill-with-docs session 2026-08-31. Design artifacts: scratchpad/issue-research-projects.md (this file), docs/adr/0012-research-projects.md.

Notes

• This is a PRD-level parent issue. Decompose via break-into-subissues into at minimum: (a) entity + manifest + scaffolding, (b) selector UI enrichment, (c) skill auto-loading (cross-repo engine changes), (d) paper-writer skill, (e) autoresearch director integration.
• The Armonia coordination layer (multi-collaborator sync) is future work; Armonia's current CONTEXT.md definition, ArmoniaService, and sidebar panel are untouched by this issue
• Vault promotion (project insights to vault) is optional, separate issue
• Per-session skill scoping (session sees only its project's skills) requires opencode engine changes, separate issue
• Problem workspaces continue for the copilot interview; no deprecation needed now
• paper/ should ship with venue-appropriate LaTeX templates (REVTeX for PRL/PRX, minimal for general use)
• Hard dependency: the !inAmicode() gate removal MUST ship together with the selector enrichment (type grouping, research metadata) to avoid showing the bare opencode selector
• Import flow handles existing files: scaffolds around, never overwrites; existing scripts/ without testbed/ gets testbed/ added inside
• Skill cache invalidation on workspace change is handled by the prepareOpencodeProject() re-run
• The paper-writer skill distinguishes hard gates (code-enforced: outline-first, section approval) from soft gates (skill instructions: provenance, forbidden actions, data grounding)
• The abstract is the last section written and must be user-authored
• The skill's data-grounding rule doubles as a correctness check
• ADR 0008 (autoresearch identity / domain pack boundary) established that quantum control is a Domain Pack, not the product. Research Projects are domain-agnostic at the project level; domain_pack in project.toml is metadata that informs context assembly, not a structural gate.