@neottia/sdlc

@neottia/sdlc compiles one canonical Plan, Build, Verify, Release, Continue, Refresh, and Adopt lifecycle into assets for a Neottia harness adapter. The compiler keeps the semantic command IDs unchanged and projects /neottia-plan, /neottia-build, /neottia-verify, /neottia-release, /neottia-continue, /neottia-refresh, and /neottia-adopt as host-facing commands. The package ships seven Markdown/Twig templates plus one plain-markdown operating-protocol template, projected as a shared neottia-sdlc skill through every adapter, and loads them before pure compilation. The compiler returns a checksummed AssetManifest for @neottia/distribution and does not read files, run providers, or install assets.

See the SDLC compiler guide and configuration reference.

Compile a lifecycle

Resolve configuration before calling the compiler. The compiler reads only the supplied snapshot, template layers, runtime package versions, and adapter. It derives provider and role instructions from the selected configuration.

import { resolveHostConfigSnapshot } from "@neottia/config-registry";
import { piHarnessAdapter, piHarnessDeclaration } from "@neottia/pi-adapter";
import { compileSdlc, createSdlcCompilerInput, loadSdlcTemplateLayers } from "@neottia/sdlc";

const snapshot = resolveHostConfigSnapshot({
  cwd: process.cwd(),
  interactive: false,
  overrides: {
    agents: {
      sdlc: {
        pi: {
          planner: { agent: "current" },
          implementer: { agent: "current" },
          verifier: { agent: "current" },
          "release-coordinator": { agent: "current" },
        },
      },
    },
  },
});

const templateLayers = await loadSdlcTemplateLayers({
  projectRoot: process.cwd(),
});
const input = createSdlcCompilerInput(snapshot, {
  compilerVersion: "0.1.0",
  harnessId: "pi",
  harnessDeclaration: piHarnessDeclaration,
  scope: "project",
  templateLayers,
  runtimePackages: [
    { logicalId: "issues", version: "0.1.0" },
    { logicalId: "design-docs", version: "0.1.0" },
  ],
});
const compilation = compileSdlc(input, piHarnessAdapter);
export const manifest = compilation.assets;

Use the installed package versions in runtimePackages. The compiler does not infer packages from provider selections. A change from filesystem Issues to GitHub Issues does not add, remove, or version a package.

Built-in instruction packs

The package includes checksummed fragments for filesystem Issues, filesystem Design Docs, local Git, disabled remote source control, GitHub, GitLab, Gitea, Forgejo, Jira, Confluence, and Bitbucket.

GitHub uses the documented gh CLI. GitLab uses glab. Both include Git-backed wiki guidance. Gitea and Forgejo require a configured MCP service for Issues and remote provider objects. Their Documents selections fail before adapter projection because this package does not claim undocumented wiki parity.

Jira Issues, Confluence Documents, and Bitbucket remote source control require configured MCP services. Their connection entries remain independent. Bitbucket uses local Git for fetch and push, then MCP for pull requests, review state, pipelines, deployments, and explicit release operations when available.

Provider connection settings live at connections.forges. A selected connection supplies a validated base URL, a credential environment-variable name, and capability-specific {server, command} MCP entries. The compiler includes only selected connections and fragments in its checksummed input. Each command template renders only the instruction blocks it uses.

See the provider instruction-pack guide for configuration, installation, authentication, supported operations, tool checks, mutation safety, and troubleshooting. Jujutsu still needs a caller-supplied pack.

Templates and roles

The package publishes templates/plan.md.twig, build.md.twig, verify.md.twig, release.md.twig, continue.md.twig, refresh.md.twig, and adopt.md.twig, plus their shared layout.md.twig, lifecycle.json prose, and protocol.md, the operating-protocol skill body with ID neottia.sdlc.protocol. Twing renders the selected command with strict variables and no HTML escaping. The shared layout has one named block per instruction slot, and command templates leave unused blocks empty. The renderer rejects nondeterministic Twig functions, duplicate instruction fragments, and missing or duplicate role fragments.

Place a plain project addition at .neottia/templates/sdlc/<command>.append.md. The compiler appends it under ## Project instructions only in the matching command. Addition files are plain Markdown, not Twig, and cannot replace canonical command content.

Place a complete project override at .neottia/templates/sdlc/<command>.md.twig. The loader rejects unknown filenames. It applies packaged, package, global, then project precedence and records selected and shadowed checksums in compiler input provenance. A whole-template override can change lifecycle policy, so review it before installation. See Customize lifecycle prompts for the accepted files and safety limits.

The Twig context exposes command, instructions, and roles. Provider and role packages supply checksummed fragments through those fields instead of owning command templates. The compiler publishes planner, researcher, implementer, reviewer, verifier, release-coordinator, and documentation-writer as portable role names.

Assign roles under agents.sdlc.<harness-id>, for example agents.sdlc.pi, agents.sdlc.opencode, or agents.sdlc.claude-code. Planner, implementer, verifier, and release coordinator need explicit selected-harness assignments. Optional roles fall back to the current agent when omitted or disabled. OpenCode and Claude Code can project named native subagents, model hints, and step limits; Claude Code maps the thinking hint to the host effort field. Pi accepts current-agent routes only. Unsupported metadata remains advisory text and never grants permissions. See the portable role assignment guide.

Safety boundaries

Generated prompts preserve lifecycle approvals, evidence requirements, stop conditions, and transitions across Pi, OpenCode, and Claude Code. Their permission language is guidance. It does not grant filesystem, process, network, merge, release, or deployment authority.

/neottia-continue recommends a next command and stops. /neottia-release never grants permission to merge, publish, or deploy. /neottia-adopt remains read-only until the user approves an exact document-operation plan, then requires a non-default branch, remote review preflight, separate deletion approvals, fresh push and draft pull-request approvals, and human review.