Spec Kit & Research Intake

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/cli/index.js
• src/cli/lib/project-state.js
• test/cli.test.js
• assets/install-manifest.json
• AGENTS.md

Delano provides a structured mechanism for transitioning from external requirements to internal project execution through its Spec Kit and Research Intake systems. These features allow operators and coding agents to import external markdown specifications and scaffold research-driven decision-making before committing to specific implementation tasks.

The Spec Kit system is designed to ingest high-level project definitions, while the Research Intake process ensures that technical uncertainties are investigated and resolved, with findings "folding forward" into canonical project artifacts such as the spec.md or plan.md.

Sources: README.md:144-162, src/cli/index.js:25-33

Spec Kit Import System

The import-spec-kit command is the primary entry point for bootstrapping a Delano project from external documentation. It transforms a supported Spec Kit-style markdown fixture into a set of planned Delano artifacts.

Architecture and Data Flow

The system reads a source markdown file and generates a directory structure within .project/projects/<slug>/. The resulting artifacts start in a planned or ready state and must pass standard Delano validation gates before activation.

The workflow ensures that external requirements are mapped to the local delivery model.
Sources: README.md:144-153, src/cli/index.js:189-213

Command Parameters

The import-spec-kit command accepts several options to customize the generated project:

Parameter	Type	Description
slug	String	Target project identifier in kebab-case.
source-md	Path	Path to the source markdown artifact.
--name	String	Overrides the project name derived from the slug.
--owner	String	Sets the project owner (defaults to team).
--lead	String	Sets the project lead (defaults to owner).
--json	Flag	Returns a machine-readable JSON result.

Sources: src/cli/index.js:197-205, test/cli.test.js:231-236

Research Intake Process

Research Intake is used when the intent of a project or task is unclear. It creates a dedicated space for investigation under an existing project's structure.

Research File Structure

Research files are isolated from the main implementation artifacts to prevent "spec drift" until findings are confirmed. They are stored in:
.project/projects/<project-slug>/research/<research-slug>/

Findings from research must be explicitly integrated into canonical artifacts or closed as no-action items.
Sources: README.md:155-162, src/cli/index.js:168-185

Research Command Interface

The research command allows agents and operators to define the scope of technical discovery.

Option	Type	Default	Description
project-slug	String	(Required)	The slug of the parent project.
research-slug	String	(Required)	Kebab-case slug for the research folder.
--title	String	"Untitled"	Human-readable title for the research.
--question	String	"None"	The primary question being investigated.
--owner	String	"team"	Owner of the research task.

Sources: src/cli/index.js:175-181, src/cli/lib/project-state.js:150-165

Implementation Details

The underlying logic for these systems relies on Delano's project-state.js library, which handles template rendering and frontmatter manipulation.

Artifact Generation

When importing or creating research, the system utilizes templates located in .project/templates/. The renderTemplate function performs token replacement (e.g., <project-name>, <ISO8601 UTC>) to ensure consistency across projects.

// Example of template rendering logic
function renderTemplate(root, templateName, replacements) {
  let text = readTemplate(root, templateName);
  for (const [token, value] of Object.entries(replacements)) {
    text = text.split(token).join(String(value));
  }
  return text;
}

Sources: src/cli/lib/project-state.js:68-75, src/cli/lib/project-state.js:170-205

Core Validation GATES

Both Spec Kit imports and Research Intake files are subject to validation by .agents/scripts/pm/validate.sh. This includes:

• Schema Validation: Ensuring spec.md and plan.md follow required structures.
• Path Safety: Verifying that no absolute local paths are leaked.
• Status Transitions: Ensuring imported projects start in the correct planned state.

Sources: README.md:150-153, AGENTS.md:38-40, test/cli.test.js:310-325

Conclusion

The Spec Kit & Research Intake systems serve as the "front door" for new work in the Delano ecosystem. By enforcing a structured import process and a formal research phase, Delano ensures that all delivery state remains traceable and that implementation only begins once technical uncertainty has been sufficiently addressed.