### Initialize and Start ACRYL Source: https://github.com/acryldev/acryl/blob/main/README.md Commands to initialize submodules, install dependencies, and launch the development environment. ```sh git submodule update --init --recursive corepack pnpm install --frozen-lockfile corepack pnpm dev ``` -------------------------------- ### Launch dsh-desktop globally Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/README.md Starts the application against the default DSH home after a global installation. ```sh dsh-desktop ``` -------------------------------- ### Start the development server Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world-plugin-guide.md Launch the graphical application for development. ```sh corepack pnpm dev ``` -------------------------------- ### Installation Workflow Diagram Source: https://github.com/acryldev/acryl/blob/main/dsh-community-market/docs/install-and-uninstall.md A Mermaid flowchart illustrating the state transitions during the plugin installation process. ```mermaid flowchart LR Scan["Complete normalized local index"] --> Candidate["Fail-closed local structural candidates"] Candidate --> Preview["Official npm verification + opaque preview"] Preview --> Operation["Recovery snapshot + reverified managed add"] Operation --> Pending["Receipt + pending next-start verification"] Pending --> Healthy["Healthy Host and Renderer"] Healthy --> Commit["Clear recovery record"] Pending -->|"failure or timeout"| Restore["Local diagnostics + configuration restore"] ``` -------------------------------- ### Initialize and build the project Source: https://github.com/acryldev/acryl/blob/main/specs/018-acryl-control-hosts/quickstart.md Prepare the repository environment by initializing submodules and installing dependencies. ```bash git submodule update --init --recursive corepack yarn install --immutable corepack yarn build ``` -------------------------------- ### Example YAML Configuration Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md A sample YAML structure for defining plugin entries. ```yaml - id: greeter name: ./greeter.ts config: greeting: Hello targets: - alpha - beta ``` -------------------------------- ### Prepare the development environment Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world-plugin-guide.md Commands to install dependencies and build the project from the repository root. ```sh corepack pnpm install --frozen-lockfile corepack pnpm upstream:install corepack pnpm upstream:build corepack pnpm build ``` -------------------------------- ### Booting a Cordis Application Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Complete example of initializing a Cordis context and loading the configuration plugin. ```typescript import { Context } from 'cordis' import { pathToFileURL } from 'node:url' import Loader from '@cordisjs/plugin-loader' const ctx = new Context() ctx.baseUrl = pathToFileURL(process.cwd()).href + '/' await ctx.plugin(Loader) await ctx.loader.create({ name: '@cordisjs/plugin-include', config: { path: './cordis.yml', }, }) ``` -------------------------------- ### Install and verify DSH Desktop Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/README.md Use these commands from the repository root to install dependencies and verify the production graph. ```sh corepack pnpm install --frozen-lockfile corepack pnpm check ``` -------------------------------- ### Launch GUI and Web interfaces Source: https://github.com/acryldev/acryl/blob/main/specs/018-acryl-control-hosts/quickstart.md Start the host using the GUI or Web presentation layers. ```bash acryl gui --profile desktop acryl web --profile desktop ``` -------------------------------- ### Start the desktop application Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/README.md Launch the application in development mode, which includes an automatic build step. ```sh yarn dev ``` -------------------------------- ### Standard HTTP GET Request Source: https://github.com/acryldev/acryl/blob/main/dsh-community-market/docs/catalog-provider-contract.md Example of a standard v1 source request using query parameters for filtering and pagination. ```text GET https://catalog.example.org/v1/plugins?q=memory&category=utility&limit=50 Accept: application/json ``` -------------------------------- ### Create Windows x64 Installer Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/README.md Run these commands in PowerShell on a native Windows x64 machine to generate an NSIS installer. This process uses bundled Node-API binaries and does not require Python or Visual Studio C++ Build Tools. ```powershell git submodule update --init --recursive corepack.cmd pnpm install --frozen-lockfile corepack.cmd pnpm dist:win ``` -------------------------------- ### Memory Provider List Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/paper-A-Programming-Paradigm-for-Spatiotemporal-Composability-Yifan-Shi-Wei-Zhang-Tianyi-Cui-Peking University-DeepSeek-AI.md Examples of concrete implementations that can satisfy the memory capability. ```text Hindsight Supermemory OpenViking Mem0 Honcho ``` -------------------------------- ### Capability Provider Examples Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Examples of specific providers for various ACRYL capability families. ```text AgentProvider Claude Code Codex Pi OpenCode Gemini CLI Kilo DSH native future agents ``` ```text MemoryProvider Hindsight Mem0 Supermemory OpenViking local SQLite future systems ``` ```text CodeGraphProvider Lat OmniGraph Graphify CodeGraph future graph systems ``` ```text ProtocolProvider ACP MCP ACRYL protocol JSON-RPC PTY bridge ``` ```text UIContribution desktop panel sidebar item status item command palette action TUI pane settings page agent inspector context meter ``` -------------------------------- ### Configure bundle package and patch Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Example structure for a plugin bundle including package.json and the corresponding patch file. ```json { "name": "dsh-my-plugin", "version": "0.1.0", "type": "module", "main": "index.js", "files": ["index.js", "cordis.patch.yml"], "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } } ``` ```yaml - insert: - id: my-plugin name: dsh-my-plugin ``` -------------------------------- ### Define Plugin Directories Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Directory structure for the generative plugin installation experiment. ```text plugin-candidates/ plugin-active/ plugin-history/ ``` -------------------------------- ### DesktopPnpm Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/docs/plugin-services.md Interface for executing pnpm commands and managing plugin installations. ```APIDOC ## DesktopPnpm ### Description Provides methods to run pnpm commands and manage plugin installations within the desktop environment. ### Methods - **run(args, signal?)**: Executes pnpm directly with the active profile directory as the working directory. - **runPlugin(args, invokingDir, signal?)**: Executes plugin-specific commands like remove or update. - **installPlugin(request)**: The primary method for installing plugins, which handles snapshots and reconciliation. - **recoveredInstallReceiptIds()**: Returns a list of receipt IDs for recovered installations. - **acknowledgeRecoveredInstall(receiptId)**: Acknowledges a recovered installation. - **rollbackPluginInstall(receiptId)**: Rolls back a specific plugin installation. ``` -------------------------------- ### Define Plugin Flow Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Workflow steps for the generative plugin installation experiment. ```text agent writes simple provider plugin -> typecheck -> unit test -> launch isolated Cordis root -> verify service appears -> dispose root -> verify cleanup -> copy/promote plugin -> edit composition -> HMR mount ``` -------------------------------- ### Configure plugin via YAML Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world-plugin-guide.md Example of providing a custom configuration value for the hello-world plugin within a YAML configuration file. ```yaml - insert: - id: hello-world name: dsh-hello-world config: greeting: Hello from ACRYL! ``` -------------------------------- ### Example runPlugin Arguments Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/docs/plugin-services.md Arguments are forwarded after the dsh plugin --profile command. ```ts ['remove', 'example-plugin'] ['update'] ['install', '--no-frozen-lockfile'] ``` -------------------------------- ### Restricted Capability Examples Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Examples of high-privilege capabilities that should not be automatically inherited by simple plugins. ```text Full Disk Access arbitrary shell update supervisor authority ``` -------------------------------- ### Define Plugin Boundaries Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Examples of appropriate and inappropriate units for plugin composition. ```text Good plugin boundary: LLM provider filesystem provider permission policy tool family memory/context system agent loop strategy UI surface Usually bad plugin boundary: one tiny pure helper function one constant one local data transform with no lifecycle/config/replacement need ``` -------------------------------- ### Handle asynchronous setup safely Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Avoid fire-and-forget asynchronous operations; use ctx.effect() with async functions to ensure proper ownership and disposal. ```ts export function apply(ctx: Context) { void connect().then(connection => { // Now who owns this if the plugin unloaded before connect resolved? }) } ``` ```ts export function apply(ctx: Context) { ctx.effect(async () => { const connection = await connect() return () => connection.close() }) } ``` -------------------------------- ### Manage profiles via CLI Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Commands for installing, inspecting, running, and removing plugins within a profile. ```bash dsh plugin --profile demo add ./my-plugin ``` ```bash dsh --profile demo --dump-config ``` ```bash dsh --profile demo ``` ```bash dsh plugin --profile demo remove dsh-my-plugin ``` -------------------------------- ### Illustrative Manifest Schema Source: https://github.com/acryldev/acryl/blob/main/dsh-community-fabric/docs/rfcs/0003-service-providers-and-composition.md Example of a plugin manifest structure demonstrating the five declaration classes. ```json { "requires": { "capabilities": { "storage.local": { "version": ">=0.1.0 <0.2.0", "optional": false } }, "services": { "git.client": { "version": ">=1.2.0 <2.0.0", "requiredFeatures": ["status"], "optionalFeatures": ["worktrees"], "optional": false, "as": "gitClient" } } }, "provides": [ { "service": "git.client", "providerId": "com.example.git-native/client", "contractVersion": "1.4.0", "features": ["status", "worktrees"], "scope": "profile" } ], "contributes": { "commands": [ { "id": "com.example.git-native.refresh", "title": "Refresh Git Status" } ] }, "permissions": { "required": [ { "name": "fs.read", "scope": "workspace" } ] }, "subscriptions": [ { "event": "workspace.changed", "version": ">=1.0.0 <2.0.0" } ] } ``` -------------------------------- ### Define Acryl Install Modes Source: https://github.com/acryldev/acryl/blob/main/specs/021-acryl-agent-plugin-ecosystem/data-model.md Specifies the operational modes for project initialization and application. ```text CREATE_PROJECT: create an isolated project, .acryl/, profile, and composition APPLY_TO_PROJECT: calculate a plan against an existing project ``` -------------------------------- ### Implement Plugin Logic with SDK Source: https://github.com/acryldev/acryl/blob/main/dsh-community-fabric/docs/architecture/compatibility-layer.md Example of defining a plugin using the Fabric SDK, demonstrating command handling and message observation. ```ts import { definePlugin } from 'dsh-community-fabric/sdk' export default definePlugin(async (ctx) => { ctx.commands.handle('com.example.hello.open', async () => { ctx.log.info('Hello from Fabric') }) ctx.messages.onReceived(async (message) => { await ctx.storage.local.set('lastMessageId', message.id) }) // Registrations are activation-scoped and released automatically. // ctx.signal aborts when this instance deactivates. }) ``` -------------------------------- ### Group Plugin Configuration Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Example YAML configuration for defining a group within a Loader. ```yaml - id: my-group name: '@cordisjs/plugin-group' group: true config: - ... ``` -------------------------------- ### Loader Entry Configuration Fields Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Examples of various fields used within a loader entry. ```yaml - id: worker name: ./worker.ts config: concurrency: 4 disabled: false ``` ```yaml name: ./plugin.ts ``` ```yaml name: some-npm-package ``` ```yaml config: timeout: 5000 ``` ```yaml disabled: true ``` -------------------------------- ### Define Capability URI Identifiers Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/paper-A-Programming-Paradigm-for-Spatiotemporal-Composability-Yifan-Shi-Wei-Zhang-Tianyi-Cui-Peking University-DeepSeek-AI.md Examples of robust capability keys encoding namespace, version, and contract identity. ```text acryl://core/memory.semantic/v1 acryl://core/agent.execution/v2 acryl://omnigraph/code.graph/v1 ``` -------------------------------- ### Run headless launcher commands Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/README.md Execute these commands to interact with the launcher without starting the full Electron application. ```sh node lib/bin.js --help node lib/bin.js --version ``` -------------------------------- ### Build and Test in WSL Linux Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/README.md Use these commands within a WSL2 environment to perform headless builds and tests. Ensure you are using a native Linux Node.js installation rather than Windows-inherited shims. ```bash source ~/.nvm/nvm.sh git submodule update --init --recursive corepack pnpm install --frozen-lockfile corepack pnpm --filter dsh-plugin-desktop run typecheck corepack pnpm --filter dsh-plugin-desktop run test corepack pnpm build ``` -------------------------------- ### DSH Tutorial Plugin Configuration Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Example YAML configuration for defining plugins including the HMR plugin within a Cordis project. ```yaml - id: logger name: '@deepseek-ai/cordis-plugin-logger-console' - id: timer name: '@deepseek-ai/cordis-plugin-timer' - id: hmr name: '@deepseek-ai/cordis-plugin-hmr' config: root: ['.'] - id: hello name: './hello.ts' ``` -------------------------------- ### Initialize and Manage Direct ACRYL Sessions Source: https://github.com/acryldev/acryl/blob/main/specs/019-acryl-harness-runtime/contracts/local-control.md Use these methods to start a host, establish a session bridge, and interact with the session lifecycle directly within the process. ```ts startDirectHost({ profile }) createAcrylSessionBridge(host.ctx, options) bridge.open(resumeSessionId?) bridge.subscribe(sessionId, listener, onError?) bridge.submitPrompt({ sessionId, text }) bridge.cancel(sessionId) ``` -------------------------------- ### Executing plugin management operations with desktopPnpm Source: https://github.com/acryldev/acryl/blob/main/docs/plugin-development.en.md Perform plugin installations and mutations using the desktopPnpm service, ensuring proper lifecycle management and recovery. ```ts await desktopPnpm.installPlugin({ invokingDir, pnpmOptions: ['--save-exact'], recovery: { packageName, packageVersion, receiptId }, signal, }) desktopPnpm.runPlugin(['remove', packageName], invokingDir, signal) desktopPnpm.runPlugin(['update'], invokingDir, signal) desktopPnpm.runPlugin(['install', '--no-frozen-lockfile'], invokingDir, signal) ``` -------------------------------- ### Dependency Cycle Diagnostic Output Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/paper-A-Programming-Paradigm-for-Spatiotemporal-Composability-Yifan-Shi-Wei-Zhang-Tianyi-Cui-Peking University-DeepSeek-AI.md Example UI output for identifying and suggesting decomposition for circular dependencies. ```text Cannot activate: session-ui → needs session.controller session-controller → needs session-ui Suggested decomposition: session-core session-ui-binding session-controller-binding ``` -------------------------------- ### Initialize tutorial environment Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world.md Commands to prepare the repository and create the tutorial directory. ```sh git submodule update --init --recursive cd deepseek-harness corepack pnpm install --frozen-lockfile mkdir -p tmp/cordis-tutorial ``` -------------------------------- ### Provenance JSON Schema Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Example structure for the provenance.json file used to record agent-generated capability metadata. ```json { "generatedBy": "agent/model identifier", "reason": "user requested FooCode support", "sourceReferences": [], "createdAt": "...", "parentGeneration": "...", "requestedPermissions": [] } ``` -------------------------------- ### Define the dsh-plugin.json manifest structure Source: https://github.com/acryldev/acryl/blob/main/dsh-community-fabric/docs/rfcs/0001-plugin-manifest-capabilities-events.md Example of a v0.1 plugin manifest defining identity, entrypoints, capability requirements, and event subscriptions. ```json { "$schema": "", "manifestVersion": "0.1.0", "id": "com.example.message-memory", "name": "Message Memory", "version": "1.2.0", "apiVersion": ">=0.1.0 <0.2.0", "entrypoints": { "host": "dist/host.js" }, "capabilities": { "required": { "messages.observe": ">=0.1.0 <0.2.0", "commands": ">=0.1.0 <0.2.0", "storage.local": ">=0.1.0 <0.2.0" }, "optional": { "ui.panel.basic": ">=0.1.0 <0.2.0" } }, "subscriptions": [ { "event": "messages.observe", "version": ">=0.1.0 <0.2.0" } ], "contributes": { "commands": [ { "id": "com.example.message-memory.show-last", "title": "Show Last Message" } ] } } ``` -------------------------------- ### Identify existing lifecycle-aware APIs Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Examples of Cordis/Harness registration APIs that automatically attach cleanup to the current Fiber. ```ts ctx.on(...) ctx.once(...) ctx.plugin(...) ``` ```ts ctx.tools.register(...) ctx.llm.registerAdapter(...) ``` -------------------------------- ### Application Bootstrapping Pattern Comparison Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Comparison between manual subsystem imports and declarative configuration-based startup. ```text BAD: main.ts manually imports and starts every application subsystem GOOD: main.ts starts Cordis + Loader configuration declares the application ``` -------------------------------- ### Host API Plugin Definition Source: https://github.com/acryldev/acryl/blob/main/dsh-community-fabric/docs/rfcs/0001-plugin-manifest-capabilities-events.md Example of a plugin definition using the Host API to handle commands and observe messages. ```ts export default definePlugin((ctx) => { ctx.commands.handle('com.example.message-memory.show-last', async () => { const lastMessageId = await ctx.storage.local.get('lastMessageId') ctx.log.info('Last observed message', { lastMessageId }) }) ctx.messages.onReceived(async (message) => { await ctx.storage.local.set('lastMessageId', message.id) }) return { deactivate() { // release resources owned by this activation }, } }) ``` -------------------------------- ### Bash tool exit code example Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Example of a process exit code that represents a successful tool execution outcome. ```text process exited code 2 ``` -------------------------------- ### Test single-writer ownership Source: https://github.com/acryldev/acryl/blob/main/specs/018-acryl-control-hosts/quickstart.md Verify that a second instance attaches to an existing session without starting a new writable runtime. ```bash acryl --profile desktop & # acquires ownership acryl --profile desktop # second instance attaches ``` -------------------------------- ### Initialize Cordis/DSH sandbox Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Commands to clone the deepseek-harness repository and prepare the tutorial directory. ```sh git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install mkdir -p tmp/cordis-tutorial cd tmp/cordis-tutorial ``` -------------------------------- ### Launch from npm Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/README.md Execute the package directly using npx. ```sh npx dsh-plugin-desktop ``` -------------------------------- ### GET /api/desktop/canvas/pty Source: https://github.com/acryldev/acryl/blob/main/specs/015-development-canvas/contracts/canvas.md Retrieves the current state and output of a PTY session. ```APIDOC ## GET /api/desktop/canvas/pty ### Description Fetches the status and current scrollback output for a specific PTY session. ### Method GET ### Endpoint /api/desktop/canvas/pty ### Query Parameters - **id** (string) - Required - The PTY session ID. ### Response #### Success Response (200) - **id** (string) - The PTY session ID. - **status** (string) - The current status. - **output** (string) - The retained scrollback output. - **exitCode** (number|null) - The exit code of the process, if finished. ``` -------------------------------- ### Initialize Cordis environment Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Commands to set up the directory structure and execute the Cordis launcher. ```sh pnpm install mkdir -p tmp/cordis-system-guide cd tmp/cordis-system-guide ``` ```sh node --import tsx ../../vendor/cordis/bin.js ``` -------------------------------- ### Typical application stack Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Recommended composition of packages for a standard Cordis application. ```text cordis + loader + include + timer + logger-console + hmr in development + your plugins ``` -------------------------------- ### HMR Plugin Configuration Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Example YAML configuration for enabling HMR in a Cordis project. ```yaml - id: timer name: '@cordisjs/plugin-timer' - id: hmr name: '@cordisjs/plugin-hmr' config: root: - . ``` -------------------------------- ### Readiness Protocol Template Source: https://github.com/acryldev/acryl/blob/main/docs/workmethodology/acryl-agent-co-developed-hybrid-engineering-methodology-github-spec-kit-matt-pocock-spec-driven-delivery-superpowers-tdd-debug-verification-cordis-lifecycle-architecture-ponytail-minimalism-vertical-slice-roadmap-ledger-execution.md Use this markdown template to establish a compact readiness report before beginning any development task. ```markdown ## Readiness - Milestone: M# - - Ledger block: specs// - Task/Subtask: T### - - Why needed: - Scope: - Acceptance proof: - Risks/open questions: ``` -------------------------------- ### Create and configure a basic plugin Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Implementation of a simple plugin and its corresponding configuration entry. ```ts import type { Context } from '@deepseek-ai/cordis' export const name = 'hello' export function apply(ctx: Context) { console.log('[hello] active') } ``` ```yaml - id: hello name: './hello.ts' ``` -------------------------------- ### Define implementation task Source: https://github.com/acryldev/acryl/blob/main/docs/workmethodology/acryl-agent-co-developed-hybrid-engineering-methodology-github-spec-kit-matt-pocock-spec-driven-delivery-superpowers-tdd-debug-verification-cordis-lifecycle-architecture-ponytail-minimalism-vertical-slice-roadmap-ledger-execution.md Use this checklist format to define executable tasks with specific paths and verification proofs. ```markdown - [ ] T001 [US1] Add behavior in exact/path.ext and verify exact proof ``` -------------------------------- ### Initialize a plugin with ctx.plugin() Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Basic usage of the plugin method to resolve and execute a plugin within the current context. ```ts const fiber = ctx.plugin(myPlugin, config) ``` -------------------------------- ### Service and Event Dispatch Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Examples of performing a direct service call versus emitting an event. ```ts await ctx.acrAgentControl.dispatch(...) ``` ```ts ctx.emit('acryl/agent-started', agent) ``` -------------------------------- ### Execute the plugin Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world.md Run the plugin using the Cordis binary and tsx loader. ```sh cd tmp/cordis-tutorial node --import tsx ../../vendor/cordis/bin.js ``` -------------------------------- ### Implement the plugin entry point Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world-plugin-guide.md The index.js file exports the plugin name and the apply function for Cordis lifecycle management. ```js export const name = 'hello-world' export function apply(ctx) { ctx.logger.info('[hello-world] Hello from Cordis!') } ``` -------------------------------- ### Create Hello World plugin Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world.md A minimal Cordis plugin implementation that logs to the console upon loading. ```ts import type { Context } from '@deepseek-ai/cordis' export const name = 'hello-world' export function apply(ctx: Context) { console.log('[hello-world] loaded') } ``` -------------------------------- ### Initialize temporary dsh directories Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world.md Create temporary directories for the plugin and dsh home to avoid affecting production configurations. ```sh mkdir -p /tmp/dsh-hello-plugin /tmp/dsh-hello-home ``` -------------------------------- ### Loader Plugin Tree Comparison Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Demonstrates the difference between manual plugin registration and declarative loader configuration. ```ts ctx.plugin(A) ctx.plugin(B) ctx.plugin(C) ``` ```yaml - id: a name: ./a.ts - id: b name: ./b.ts - id: c name: ./c.ts ``` -------------------------------- ### Cordis Onboarding Prompt for Coding Agents Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Use this prompt when delegating tasks to ensure the agent follows Cordis lifecycle and service injection rules. ```text This repository uses DeepSeek Harness's vendored @deepseek-ai/cordis. Treat vendor/cordis and generated subsystem types/docs as authoritative over generic upstream examples. Cordis plugins are lifecycle units. Hard service requirements go in inject and are live: consumers unload/re-activate when provider implementations change. Every registration/resource must be owned by the current Fiber; ctx.on, ctx.plugin, service provisioning, ctx.tools.register and ctx.llm.registerAdapter are lifecycle-aware, while raw timers/watchers/connections must be wrapped in ctx.effect with cleanup. PENDING is a valid missing-dependency state. Current Fiber states are PENDING, LOADING, ACTIVE, FAILED, UNLOADING, DISPOSED; there is no public INACTIVE enum. Use services for direct capabilities, events for open extension points, and always call next() in waterfall observers unless intentionally vetoing. A Harness tool is not a Cordis primitive: it is registered into ctx.tools and should return a canonical typed value separate from model/UI rendering. Assume plugins can be hot- reloaded and activated repeatedly. Test provider removal/replacement and disposal, not only startup. Before coding, inspect the owning docs/subsystems page and local package types. ``` -------------------------------- ### Waterfall contract test implementation Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Example of a middleware listener used to verify delegation order in a waterfall. ```ts ctx.on('my/request', async (req, next) => { trace.push('outer-before') const result = await next() trace.push('outer-after') return result }) ``` -------------------------------- ### Declare Client package configuration Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world.md Include this in package.json to register the client platform and runtime injection. ```json { "dsh": { "client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-runtime"] } }, "exports": { "./client": { "default": "./lib/client.js" } } } ``` -------------------------------- ### Await plugin startup Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Ensure a plugin has finished loading before proceeding with further operations. ```ts const fiber = ctx.plugin(myPlugin) await fiber ``` ```ts await fiber.await() ``` -------------------------------- ### Implement an asynchronous disposer Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Example of an effect returning an async function to handle cleanup that requires awaiting. ```ts ctx.effect(async () => { const connection = await openConnection() return async () => { await connection.flush() await connection.close() } }) ``` -------------------------------- ### Host and Activation Lifecycle States Source: https://github.com/acryldev/acryl/blob/main/dsh-community-fabric/docs/rfcs/0001-plugin-manifest-capabilities-events.md State transitions for the Host product and individual plugin activation instances. ```text starting → ready → stopping → stopped ``` ```text discover → validate → negotiate → authorize → activating → active → deactivating → disposed ``` -------------------------------- ### Avoid manual startup choreography Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Define dependencies through injection rather than manually awaiting startup functions. ```ts await loadDatabase() await loadApi() await loadWorker() ``` -------------------------------- ### GET /v1/plugins Source: https://github.com/acryldev/acryl/blob/main/dsh-community-market/docs/catalog-provider-contract.md Retrieves a list of catalog plugins based on search queries, categories, and other filter criteria. ```APIDOC ## GET /v1/plugins ### Description Retrieves a list of catalog plugins. The request is filtered based on the parameters supported by the source manifest. ### Method GET ### Endpoint /v1/plugins ### Parameters #### Query Parameters - **q** (string) - Optional - Trimmed search text, 1–200 characters. - **category** (string) - Optional - Stable category IDs. Repeated values act as a multi-select OR filter. - **capability** (string) - Optional - Fabric/host capability IDs. Repeated values act as an AND filter. - **cursor** (string) - Optional - Opaque continuation value for pagination. - **limit** (integer) - Optional - Number of items to return (1-100). - **sort** (string) - Optional - Sort order: relevance, updated, name, or downloads. - **locale** (string) - Optional - BCP 47-like language tag. ``` -------------------------------- ### Define a Plugin with Dependencies and Bindings Source: https://github.com/acryldev/acryl/blob/main/dsh-community-fabric/docs/rfcs/0003-service-providers-and-composition.md Demonstrates the plugin authoring experience using dependency injection and provider binding. Note that arbitrary service lookup is prohibited and bindings must match declared provider IDs. ```ts export default definePlugin((ctx) => { // Generated from requires.services[...].as; no arbitrary service lookup. const git = ctx.dependencies.gitClient // Binding is allowed only for the providerId declared in provides. ctx.providers.bind('com.example.git-native/client', createGitClient(ctx)) ctx.commands.handle('com.example.git-native.refresh', async ({ signal }) => { return git.status({ signal }) }) }) ``` -------------------------------- ### Agent Provider Seam Definition Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Example structure for the Agent Provider seam including definitions, providers, and consumers. ```text Agent Provider Seam Definition: @acryl/contracts/agent-provider Providers: @acryl/agent-claude-code @acryl/agent-codex @acryl/agent-pi @acryl/agent-opencode @acryl/agent-dsh-native Consumers: room runtime session UI relay service orchestrators commands ``` -------------------------------- ### Raw interval side effect Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md An example of an unmanaged side effect that can lead to memory leaks and duplicate work. ```ts const timer = setInterval(work, 1000) ``` -------------------------------- ### Expected output Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world.md The console output confirming the plugin has loaded successfully. ```text [hello-world] loaded ``` -------------------------------- ### Add electron dependency to a profile Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/README.md Installs the electron peer dependency within a specific profile when using pnpm. ```sh dsh plugin --profile add electron ``` -------------------------------- ### Implement Heartbeat Plugin Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Demonstrates using the timer plugin versus raw resource management for interval tasks. ```ts import type { Context } from 'cordis' import type {} from '@cordisjs/plugin-timer' export const name = 'heartbeat' export const inject = ['timer'] export function apply(ctx: Context) { ctx.interval(() => { ctx.logger('heartbeat').debug('tick') }, 5000) } ``` ```ts export function apply(ctx: Context) { ctx.effect(() => { const timer = setInterval(() => { ctx.logger('heartbeat').debug('tick') }, 5000) return () => clearInterval(timer) }) } ``` -------------------------------- ### Create Root Context Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Initializes the root dependency, service, and lifecycle container. ```typescript const ctx = new Context() ``` -------------------------------- ### Initialize root Context Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Demonstrates the standard initialization of a root Context in the DeepSeek Harness environment. ```ts import { Context } from '@deepseek-ai/cordis' const root = new Context() ``` -------------------------------- ### Preferred Modular Project Structure Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Recommended file organization separating the bootstrap logic from the runtime and plugin implementations. ```text electron/ bootstrap.mjs runtime/ host.ts plugins/ desktop-window/ desktop-tray/ desktop-terminal/ desktop-menu/ desktop-workspace/ desktop-update/ ``` -------------------------------- ### Define a DSH Plugin Source: https://github.com/acryldev/acryl/blob/main/dsh-community-fabric/docs/research/dsh-plugin-needs.md Example of using the definePlugin SDK function to register tools, observe messages, and bind UI renderers. ```ts import { definePlugin } from 'dsh-community-fabric/sdk' export default definePlugin((ctx) => { ctx.tools.register('com.example.export', exportTool) ctx.messages.observe('received', event => { ctx.log.debug('message received', { id: event.id }) }) ctx.ui.toolResults.bind('com.example.export.result', exportResultRenderer) }) ``` -------------------------------- ### Manage Plugins and Dependencies Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Use these methods for plugin loading and dependency injection within the Cordis context. ```ts ctx.plugin(...) ctx.inject(...) ``` -------------------------------- ### Run headless repository smoke tests Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world-plugin-guide.md Commands to verify the profile composition without launching the graphical interface. ```sh corepack pnpm --filter dsh-plugin-desktop run build corepack pnpm --filter dsh-plugin-desktop run verify:profile ``` -------------------------------- ### Define a minimal Cordis tool Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md A complete example of a tool plugin using defineTool, including parameter validation and execution logic. ```ts import type { Context } from '@deepseek-ai/cordis' import { defineTool } from '@deepseek-ai/dsh-tools' export const name = 'greet-tool' export const inject = ['tools'] export function apply(ctx: Context) { ctx.tools.register(defineTool({ name: 'greet', description: 'Greet someone by name.', parameters: { name: { type: 'string', required: true, description: 'The name to greet', }, }, output: { schema: { type: 'string' }, render: (_args, value) => [ { type: 'text', text: value }, ], }, async execute(args) { return `Hello, ${args.name}!` }, })) } ``` -------------------------------- ### Phase A Dependency Strategy Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Initial phase using an adapter package to pin the Cordis version. ```text ACRYL | +-- @acryl/runtime-cordis | +-- pinned Cordis version ``` -------------------------------- ### Avoid independent effects for ordered teardown Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Example of an anti-pattern where dependent resources are cleaned up in separate effects, risking race conditions. ```ts ctx.effect(() => { const db = openDb() return async () => db.close() }) ctx.effect(() => { const writer = createWriter(/* depends on db */) return async () => writer.flush() }) ``` -------------------------------- ### Expected plugin output Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md The console output after running the hello plugin. ```text [hello] active ``` -------------------------------- ### Cordis registration APIs Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Examples of built-in Cordis APIs that already handle lifecycle ownership and do not require manual wrapping in ctx.effect. ```ts ctx.on(...) ctx.plugin(...) ctx.provide(...) ``` -------------------------------- ### Get PTY Session Status Response Source: https://github.com/acryldev/acryl/blob/main/specs/015-development-canvas/contracts/canvas.md Retrieves the current status, scrollback output, and exit code for a specific PTY session. ```json { "id": "pty_…", "status": "running", "output": "…", "exitCode": null } ``` -------------------------------- ### Manage architecture and plugin lifecycle Source: https://github.com/acryldev/acryl/blob/main/specs/018-acryl-control-hosts/quickstart.md Commands for inspecting architecture state and managing plugin lifecycle events. ```bash acryl architecture --plane host --json acryl plugin enable --json acryl plugin reload --json ``` -------------------------------- ### Run dsh web with patch Source: https://github.com/acryldev/acryl/blob/main/docs/cordisplugins/hello-world.md Launch the dsh web environment using the specified temporary home and plugin patch. ```sh cd deepseek-harness DSH_HOME=/tmp/dsh-hello-home corepack pnpm dsh web --patch /tmp/dsh-hello-plugin/cordis.yml ``` -------------------------------- ### ACRYL Agent Adapter Request Flow Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md The automated steps taken by ACRYL to integrate a new agent adapter without requiring an installer release. ```text 1. research FooCode CLI/API 2. infer adapter contract 3. generate @acryl/agent-foocode 4. test spawn/send/stream/interrupt/resume/stop 5. stage plugin 6. mount through Cordis 7. register AgentProvider 8. UI/TUI automatically exposes FooCode 9. observe failures 10. rollback plugin if necessary ``` -------------------------------- ### Create Windows x64 Portable ZIP Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/README.md Generate an unsigned portable ZIP archive for testing without installation. Note that this build is unsigned and may trigger security warnings. ```powershell corepack.cmd pnpm dist:win-portable ``` -------------------------------- ### Handle required vs optional dependencies Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Use inject for mandatory services or ctx.get for optional ones that allow the plugin to function without the capability. ```ts export const inject = ['metrics'] export function apply(ctx: Context) { ctx.metrics.record('loaded', 1) } ``` ```ts export function apply(ctx: Context) { const metrics = ctx.get('metrics') metrics?.record('loaded', 1) } ``` -------------------------------- ### Implement Reporter Plugin Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md A plugin that injects the greeter service and listens for greeter events. ```ts import type { Context } from 'cordis' import type {} from './greeter.ts' export const name = 'reporter' export const inject = ['greeter'] export function apply(ctx: Context) { const logger = ctx.logger('reporter') ctx.on('greeter/called', (name) => { logger.info('greeted %s', name) }) logger.info(ctx.greeter.greet('Cordis')) } ``` -------------------------------- ### Direct Service Provisioning Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Use ctx.provide for lightweight service values that do not require a full Service subclass. ```typescript declare module 'cordis' { interface Context { featureFlags: FeatureFlags } } export function apply(ctx: Context) { const flags = new FeatureFlags() ctx.provide('featureFlags', flags) } ``` -------------------------------- ### Implement a Catalog Adapter Source: https://github.com/acryldev/acryl/blob/main/dsh-community-market/docs/catalog-adapter-guide.md A complete skeleton for a catalog adapter, including raw data parsing, URL construction, and snapshot generation. ```ts import type { CatalogQuery, CatalogSnapshot } from '../contracts/index.js' import type { CatalogAdapter, CatalogFetchContext } from '../contracts/types.js' import { parseCatalogSnapshot } from '../contracts/validate.js' const ADAPTER_ID = 'market.example-provider-v1' const ENDPOINT = 'https://catalog.example.org/api/plugins' const ORIGIN = new URL(ENDPOINT).origin const DEFAULT_PAGE_LIMIT = 50 const MAX_PAGE_LIMIT = 100 interface RawPlugin { readonly id: string readonly title: string readonly summary: string readonly npm: string readonly categories?: readonly string[] } interface RawPage { readonly plugins: readonly RawPlugin[] readonly next?: string readonly total?: number } function readRawPage(value: unknown, effectiveLimit: number): RawPage { if (value === null || typeof value !== 'object' || Array.isArray(value)) { throw new Error('example provider response is not an object') } const record = value as Record if (!Array.isArray(record.plugins) || record.plugins.length > effectiveLimit) { throw new Error('example provider page is invalid') } const plugins = record.plugins.map((entry): RawPlugin => { if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) { throw new Error('example provider item is invalid') } const item = entry as Record if ( typeof item.id !== 'string' || typeof item.title !== 'string' || typeof item.summary !== 'string' || typeof item.npm !== 'string' || (item.categories !== undefined && (!Array.isArray(item.categories) || item.categories.some(value => typeof value !== 'string'))) ) { throw new Error('example provider item fields are invalid') } return { id: item.id, title: item.title, summary: item.summary, npm: item.npm, ...(item.categories === undefined ? {} : { categories: item.categories as string[] }), } }) if (record.next !== undefined && (typeof record.next !== 'string' || record.next.length === 0)) { throw new Error('example provider cursor is invalid') } if (record.total !== undefined && ( typeof record.total !== 'number' || !Number.isSafeInteger(record.total) || record.total < 0 )) { throw new Error('example provider total is invalid') } return { plugins, ...(record.next === undefined ? {} : { next: record.next as string }), ...(record.total === undefined ? {} : { total: record.total as number }), } } function requestUrl(query: CatalogQuery, effectiveLimit: number): URL { const url = new URL(ENDPOINT) if (query.q !== undefined) url.searchParams.set('search', query.q) for (const category of query.category ?? []) url.searchParams.append('tag', category) if (query.cursor !== undefined) url.searchParams.set('after', query.cursor) url.searchParams.set('pageSize', String(effectiveLimit)) return url } function snapshot( raw: RawPage, responseFinalUrl: string, context: CatalogFetchContext, ): CatalogSnapshot { return parseCatalogSnapshot({ schemaVersion: '1.0.0', source: { sourceRecordId: context.source.sourceRecordId, providerId: context.source.providerId, adapterId: context.source.adapterId, registrationKind: context.source.registrationKind, fetchedAt: new Date().toISOString(), finalUrl: responseFinalUrl, }, items: raw.plugins.map(item => ({ id: item.id, name: item.npm, displayName: item.title, summary: item.summary, ...(item.categories === undefined ? {} : { categories: [...item.categories] }), package: { registry: 'npm', name: item.npm }, provenance: { sourceRecordId: context.source.sourceRecordId, providerId: context.source.providerId, itemId: item.id, }, })), page: { ...(raw.next === undefined ? {} : { nextCursor: raw.next }), ...(raw.total === undefined ? {} : { total: raw.total }), }, }) } export const exampleProviderAdapter: CatalogAdapter = { adapterId: ADAPTER_ID, async fetch(query, context) { const effectiveLimit = Math.min(query.limit ?? DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT) const response = await context.http.getJson( requestUrl(query, effectiveLimit).href, context.signal, { allowedOrigin: ORIGIN }, ) if (new URL(response.finalUrl).origin !== ORIGIN) { throw new Error('example provider response changed the reviewed origin') } return snapshot(readRawPage(response.value, effectiveLimit), response.finalUrl, context) }, } ``` -------------------------------- ### Handoff Summary Template Source: https://github.com/acryldev/acryl/blob/main/docs/workmethodology/acryl-agent-co-developed-hybrid-engineering-methodology-github-spec-kit-matt-pocock-spec-driven-delivery-superpowers-tdd-debug-verification-cordis-lifecycle-architecture-ponytail-minimalism-vertical-slice-roadmap-ledger-execution.md Use this markdown structure to document task completion and provide context for future agents. ```markdown ## Handoff / Result - Objective and task ID - Completed behavior - Changed files - Tests and command output summary - Commit hashes - Decisions and assumptions - Open problems and risks - Exact next recommended task ``` -------------------------------- ### Electron Bootstrap Architecture Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Simplified architectural flow when utilizing Electron as the host environment. ```text tiny Electron bootstrap | Cordis-managed desktop services | ACRYL runtime ``` -------------------------------- ### Initialize Git Submodules Source: https://github.com/acryldev/acryl/blob/main/specs/000-wayfinding/issues/03-init-pinned-harness.md Execute this command to initialize and update all submodules recursively within the repository. ```bash git submodule update --init --recursive ``` -------------------------------- ### Manage plugins with explicit profile Source: https://github.com/acryldev/acryl/blob/main/docs/user-guide.en.md Use the desktop profile explicitly to manage plugins via the CLI. ```sh dsh plugin --profile desktop add dsh plugin --profile desktop remove dsh plugin --profile desktop update ``` -------------------------------- ### Implement cross-environment plugin manager Source: https://github.com/acryldev/acryl/blob/main/dsh-plugin-desktop/docs/plugin-services.md Uses a nested ctx.inject() callback to conditionally load Desktop services only when the desktopProfiles service is available, falling back to an ordinary DSH adapter otherwise. ```ts import type { Context } from '@deepseek-ai/cordis' import type {} from 'dsh-plugin-desktop/profile-service' import type {} from 'dsh-plugin-desktop/pnpm' export const name = 'cross-environment-plugin-manager' export const inject = ['webServer', 'loader'] interface ManagerAdapter { readonly profile: string readonly profileDir?: string runPlugin( args: readonly string[], invokingDir: string, signal?: AbortSignal, ): unknown } declare function mountManager(ctx: Context, adapter: ManagerAdapter): () => void declare function ordinaryDshAdapter(profile: string): ManagerAdapter export function apply(ctx: Context, config: { profile?: string }): void { const profiles = ctx.get('desktopProfiles') if (profiles === undefined) { // Existing non-Desktop behavior remains authoritative here. const profile = config.profile ?? 'web' ctx.effect( () => mountManager(ctx, ordinaryDshAdapter(profile)), 'example: ordinary DSH plugin manager', ) return } // ctx.inject() still treats desktopPnpm as required for this nested // callback. The parent plugin remains loadable in ordinary DSH because the // Desktop-only dependency is not in its top-level inject list. ctx.inject(['desktopPnpm'], (desktopCtx) => { desktopCtx.effect(() => mountManager(desktopCtx, { profile: profiles.current.name, profileDir: profiles.current.dir, runPlugin: (args, invokingDir, signal) => desktopCtx.desktopPnpm.runPlugin(args, invokingDir, signal), }), 'example: Desktop plugin manager') }) } ``` -------------------------------- ### Mounting the Timer Plugin Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Configuration to register the timer plugin and the resulting context property. ```yaml - id: timer name: '@cordisjs/plugin-timer' ``` ```ts ctx.timer ``` -------------------------------- ### Architectural Comparison: DSH vs ACRYL Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Comparison of the agent loop emphasis between DeepSeek Harness and the ACRYL Room architecture. ```text DSH emphasis: model -> DSH agent loop -> tools ACRYL emphasis: ACRYL Room | +--------------+--------------+ | | | Claude Code Codex Pi | | | +--------------+--------------+ | relay/context ``` -------------------------------- ### Accessing Services on Context Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Demonstrates how named capabilities are accessed via the context object. ```ts ctx.tools ctx.llm ctx.database ``` -------------------------------- ### Task Tracking Template Source: https://github.com/acryldev/acryl/blob/main/docs/workmethodology/acryl-agent-co-developed-hybrid-engineering-methodology-github-spec-kit-matt-pocock-spec-driven-delivery-superpowers-tdd-debug-verification-cordis-lifecycle-architecture-ponytail-minimalism-vertical-slice-roadmap-ledger-execution.md Track individual tasks with dependencies and RED/GREEN proof commands. ```markdown - [ ] T### [US#] in ``. - Why: - Depends on: - RED/GREEN proof: `` - Acceptance: ``` -------------------------------- ### Perform manual TUI acceptance testing Source: https://github.com/acryldev/acryl/blob/main/specs/019-acryl-harness-runtime/quickstart.md Commands to build and launch the TUI for manual verification of session persistence and headless mode. ```bash corepack pnpm --filter acryl-tui run build node acryl-tui/lib/bin.js tui --profile acryl ``` ```bash node acryl-tui/lib/bin.js tui --profile acryl --resume ``` ```bash node acryl-tui/lib/bin.js tui --profile acryl --json ``` -------------------------------- ### Execute Cordis Scaffolding Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Command to initiate the project scaffolding workflow. ```sh npm create cordis ``` -------------------------------- ### Avoid YAML startup order Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_practical_tutorial_spec.md Do not rely on file order in YAML for dependency timing; instead, use the inject array to explicitly define relationships. ```yaml # "database must be first" - name: ./database.ts - name: ./api.ts - name: ./workers.ts ``` ```typescript // api.ts export const inject = ['database'] ``` ```typescript // workers.ts export const inject = ['api'] ``` -------------------------------- ### List core runtime machinery Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Lists the core properties initialized by the root Context. ```text ctx.events ctx.logger ctx.reflect ctx.registry ctx.fiber ctx.root ``` -------------------------------- ### Define ACRYL Harness Runtime interfaces and boot API Source: https://github.com/acryldev/acryl/blob/main/docs/superpowers/specs/2026-08-26-acryl-harness-runtime-design.md Defines the configuration options for booting the harness, the runtime interface, and the primary boot function. ```ts interface BootAcrylHarnessProfileOptions { profile: string prepare(ctx: Context): Promise | void } interface AcrylHarnessRuntime { ctx: Context profileDirectory: string dispose(): Promise } function bootAcrylHarnessProfile( options: BootAcrylHarnessProfileOptions, ): Promise ``` -------------------------------- ### Project File Structure Source: https://github.com/acryldev/acryl/blob/main/docs/superpowers/specs/2026-08-26-standalone-native-provider-durable-chat-design.md Overview of the relevant source files for the durable chat implementation across the harness runtime and TUI components. ```text acryl-harness-runtime/src/durable-message.ts # extend result/projection contract acryl-harness-runtime/src/native-agent.ts # runtime-owned native message port acryl-harness-runtime/src/index.ts # create session and expose the handle acryl-harness-runtime/tests/native-agent.spec.ts # real Harness-facing RED/GREEN tests acryl-tui/src/host/direct.ts # obtain selected session and port acryl-tui/src/render/app.tsx # forward them to Ink acryl-tui/src/render/ink-app.tsx # render durable transcript/results acryl-tui/tests/ink-app.spec.tsx # human-visible projection behavior acryl-tui/tests/direct.spec.ts # owner-host durable session integration ``` -------------------------------- ### Define context graph provider dependencies Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_system_guide_for_coding_agents.md Shows the preferred way to reference a service capability versus concrete implementations. ```text ctx.codeGraph ``` ```text OmniGraph SDK concrete client Lat.md concrete implementation ``` -------------------------------- ### Plugin Source File Formats Source: https://github.com/acryldev/acryl/blob/main/docs/cordis/cordis_spec.md Supported file extensions for plugin authoring and runtime generation. ```text .ts developer/generated typed plugin .mjs direct runtime-generated JavaScript plugin ```