Preface¶

When developing projects with DeepSeek Harness (DSH), ideas evolve rapidly and manual documentation often falls behind. volens addresses this problem by maintaining an append-only decision log and automatically deriving and refreshing design documents.

What Is It¶

volens is a workflow plugin maintained by funcpn. Its core value is keeping project design documents in sync with decisions and preventing documentation from becoming invalid due to later decisions.

Core Features¶

1. Append-only decision log: Maintains a log file that can only be appended to and not modified (docs/DECISION-LOG.md), recording each design decision.
2. Derived design documents: Automatically generates or updates design documents (docs/DESIGN.md) from the decision log, keeping documentation consistent with decisions.
3. Automatic synchronization mechanism: Automatically runs at the beginning of each DSH turn, synchronizing new decisions into design documents.
4. Instruction contract module: Adds a contract module to the project’s instruction file, defining the documentation model and collaboration conventions.
5. Language preference configuration: Creates a project-level language preference file (docs/.volens/lang) to specify the documentation language.
6. Synchronization cursor management: Creates a synchronization cursor file (docs/.volens-cursor) that records the log line count to which design documents have been synchronized.

Installation and Activation¶

Installing this plugin in DSH requires the following steps:

# 1. 添加插件市场
/plugin marketplace add

# 2. 安装插件
/plugin install volens

Typical Usage¶

1. Initialization: Run the command once in the project root directory:

    /volens

2. Recording decisions: Each time a design decision is made, append an entry to docs/DECISION-LOG.md. The entry structure usually includes context, decision, and consequences.
3. Automatic synchronization: No manual operation is required. The synchronization mechanism automatically runs at the beginning of each DSH turn, injecting new decisions into the context and updating docs/DESIGN.md.

Use Cases and Considerations¶

• Runtime environment: DSH runs the plugin within its own process and does not require a bash environment.
• Data safety: The plugin does not make network requests, contains no telemetry or analytics, and data does not leave the local machine.
• File permissions: The plugin only reads from and writes to files within the docs/ directory and does not execute any code in the project.
• Blocking behavior: In DSH, the plugin returns an empty decision and does not block the current turn.
• Subagent isolation: DSH does not inject the synchronization mechanism into subagent sessions.

Summary¶

volens addresses the problem of lagging documentation in agent development through an append-only decision log and automatically derived design documents. It keeps design documents in sync with current decisions and reduces the risk of hallucinations.

View the catalog page
View the source code