Adding AI Agent Rendering System

Add a new AI agent rendering system to Packmind, supporting both single-file (like AGENTS.md) and multi-file (like Cursor/Continue) patterns, including type definitions, deployer implementation, registry registration, frontend UI integration, documentation updates, and comprehensive tests following Packmind test standards.

When to Use

• When adding support for a new AI coding assistant (e.g., Continue, Cursor, Claude Code, GitHub Copilot, OpenCode)

• When implementing a new rendering format for standards and recipes distribution

• When extending Packmind to support additional AI agent integrations

• When creating a new deployer that follows the ICodingAgentDeployer interface

Prerequisites — Gather from User

Before proceeding, the following information must be known. If any of these are unclear or not provided, prompt the user to clarify before starting implementation.

1. What is the agent's identifier key and display name?

   • The identifier key is the snake_case string used in code (CodingAgent type, CodingAgents record, AGENT_FILE_PATHS, etc.). Examples: opencode, gitlab_duo, continue, agents_md.
   • The display name is the human-readable label shown in the frontend UI and CLI. Examples: OpenCode, GitLab Duo, Continue, AGENTS.md.
   • Both values are reused consistently across all steps (type definitions, deployer class, registry, frontend labels, CLI display names, documentation).

2. In which directories will Standards be rendered?

   • Multi-file example: .agent/rules/ (one file per standard)
   • Single-file example: AGENTS.md, .agent/guidelines.md (all standards aggregated into one file)
   • Hybrid is possible (single-file standards + multi-file commands/skills)

3. In which directories will Commands be rendered?

   • If the agent supports native slash commands: provide the directory (e.g., .agent/commands/)
   • If the agent does NOT support native slash commands, say so explicitly. Commands will be deployed to .packmind/commands/ as a fallback (same pattern used by GitLab Duo, Junie, and AGENTS.md agents). Users invoke them via @.packmind/commands/command-name.md.

4. In which directories will Skills be rendered?

   • Example: .agent/skills/
   • If the agent does not support skills, say so explicitly. An empty string will be used in CodingAgentArtefactPaths.

5. If standards are rendered into a shared file like AGENTS.md: What should be the precedence rules?

   • Multiple agents can write to the same file (e.g., both OpenCode and agents_md write to AGENTS.md).
   • Position in RENDER_MODE_ORDER determines priority — agents later in the array supersede agents earlier when both are active.
   • Specify where this new agent should sit relative to existing agents that share the same file.

6. What frontmatter format does the agent require? (YAML, Markdown, plain text, none)

7. What file extensions should be used? (.md, .mdc, .txt, etc.)

8. What naming convention should be used for files? (e.g., packmind-standard-{slug}.md, standard-{slug}.mdc)

9. Does the agent require specific frontmatter properties? (name, globs, alwaysApply, description, etc.)

10. What is the relative path from agent files to .packmind/standards/ directory?

Convention: Throughout all recipe steps below, NEW_AGENT / new_agent / NewAgent are placeholders for the identifier key (from prerequisite 1), and 'New Agent' is a placeholder for the display name. Substitute both consistently in every step.

Recipe Steps

Step 1: Add RenderMode enum value

Add the new AI agent to the RenderMode enum in packages/types/src/deployments/RenderMode.ts. Add the enum value and include it in the RENDER_MODE_ORDER array to ensure proper ordering. Position matters for supersedence: agents earlier in the array are overridden by agents later in the array when they share a file.

export enum RenderMode {
  // ... existing values
  NEW_AGENT = 'NEW_AGENT',
}

export const RENDER_MODE_ORDER: RenderMode[] = [
  // ... existing values
  RenderMode.NEW_AGENT,
];

Step 2: Add CodingAgent type

Add the new agent identifier to the CodingAgent union type in both packages/types/src/coding-agent/CodingAgent.ts and packages/coding-agent/src/domain/CodingAgents.ts. Also add it to the CodingAgents record object.

export type CodingAgent =
  | 'packmind'
  | 'junie'
  | 'claude'
  | 'cursor'
  | 'copilot'
  | 'agents_md'
  | 'gitlab_duo'
  | 'continue'
  | 'new_agent';

export const CodingAgents: Record<CodingAgent, CodingAgent> = {
  // ... existing values
  new_agent: 'new_agent',
};

Step 3: Add CodingAgentArtefactPaths

If the agent supports commands, standards, or skills as multi-file artifacts, add it to packages/types/src/coding-agent/CodingAgentArtefactPaths.ts:

1. Add the agent to the MultiFileCodingAgent type union
2. Add directory path mappings in the CODING_AGENT_ARTEFACT_PATHS record for each supported artifact type (command, standard, skill). Use empty string for unsupported artifact types.

export type MultiFileCodingAgent = Extract<CodingAgent, 'claude' | 'cursor' | ... | 'new_agent'>;

export const CODING_AGENT_ARTEFACT_PATHS: Record<MultiFileCodingAgent, { command: string; standard: string; skill: string }> = {
  // ... existing values
  new_agent: {
    command: '.new-agent/commands/',
    standard: '',  // empty if standards are single-file (embedded in a shared file)
    skill: '.new-agent/skills/',
  },
};

Step 4: Add to VALID_CODING_AGENTS

Add the agent identifier to the VALID_CODING_AGENTS array in packages/types/src/coding-agent/validation.ts. This enables validation of the agent string in configuration files.

export const VALID_CODING_AGENTS: CodingAgent[] = [
  // ... existing values
  'new_agent',
];

Update the corresponding test in validation.spec.ts to include the new agent in test fixtures.

Step 5: Add RenderMode to CodingAgent mapping

Add the mapping from RenderMode to CodingAgent in packages/types/src/deployments/RenderModeCodingAgentMapping.ts in the RENDER_MODE_TO_CODING_AGENT record.

export const RENDER_MODE_TO_CODING_AGENT: Record<RenderMode, CodingAgent> = {
  // ... existing mappings
  [RenderMode.NEW_AGENT]: CodingAgents.new_agent,
};

Step 6: Create Deployer class

Create a new deployer class in packages/coding-agent/src/infra/repositories/{agentName}/{AgentName}Deployer.ts. Choose a base class based on the agent's rendering pattern:

• SingleFileDeployer: For agents that aggregate all standards into one file (e.g., AGENTS.md, CLAUDE.md). Can also be extended with multi-file methods for commands/skills (hybrid pattern).
• MultiFileDeployer: For agents that create one file per standard (e.g., Cursor, Continue).
• ICodingAgentDeployer: Implement directly for fully custom behavior.

For hybrid agents (single-file standards + multi-file commands/skills), extend SingleFileDeployer and override the artifact methods:

import { SingleFileDeployer } from '../singleFile/SingleFileDeployer';

export class NewAgentDeployer extends SingleFileDeployer {
  // Implement required methods:
  // - deployRecipes() - deploy standards/recipes content
  // - deploySkills() - deploy skill files to agent directories
  // - deployArtifacts() - deploy command files to agent directories
  // - generateRemovalFileUpdates() - handle artifact removal
  // - generateAgentCleanupFileUpdates() - handle full agent cleanup
}

Step 7: Implement frontmatter generation

In the deployer, implement frontmatter generation based on the agent's requirements. For Continue-style agents, include name, globs (if scope exists), alwaysApply (false if scope, true otherwise), and description (from summary or standard name). For Cursor-style agents, use simpler frontmatter with just globs and alwaysApply. For single-file agents, frontmatter may not be needed.

// For Continue-style (with name and description)
const frontmatter = standardVersion.scope && standardVersion.scope.trim() !== ''
  ? `---
name: ${standardVersion.name}
globs: ${standardVersion.scope}
alwaysApply: false
description: ${summary}
---`
  : `---
name: ${standardVersion.name}
alwaysApply: true
description: ${summary}
---`;

// For Cursor-style (simpler)
const frontmatter = standardVersion.scope && standardVersion.scope.trim() !== ''
  ? `---
globs: ${standardVersion.scope}
alwaysApply: false
---`
  : `---
alwaysApply: true
---`;

Step 8: Register deployer in registry

Register the new deployer in packages/coding-agent/src/infra/repositories/CodingAgentDeployerRegistry.ts by importing it and adding a case in the createDeployer switch statement. Also add the agent to the canCreateDeployer method.

If the agent supports multi-file artifacts (commands/skills), also add it to the isMultiFileAgent() check if that method exists.

import { NewAgentDeployer } from './newAgent/NewAgentDeployer';

private createDeployer(agent: CodingAgent): ICodingAgentDeployer {
  switch (agent) {
    // ... existing cases
    case 'new_agent':
      return new NewAgentDeployer(this.standardsPort, this.gitPort);
    default:
      // An unreachable switch arm is our bug, not the caller's: PackmindInternalError
      // keeps the 500 and the stack, puts `agent` in the log as a field, and withholds
      // the message from the response. A bare Error would do none of that.
      throw new PackmindInternalError(
        'unknown_coding_agent',
        { agent },
        `No deployer is registered for coding agent "${agent}".`,
      );
  }
}

private canCreateDeployer(agent: CodingAgent): boolean {
  return (
    // ... existing agents
    agent === 'new_agent'
  );
}