dsh-project-j4agent

J4Agent

English | 中文

Agent-native Software Development Lifecycle Management for DeepSeek Harness

Not Jira for Agents. A development model designed for how humans and coding Agents actually build software together.

J4Agent is a lightweight development-management layer for DeepSeek Harness. It connects requirements, implementation work, verification evidence, revision state, artifacts and releases as shared project facts that both humans and Agents can understand.

---

Does this sound familiar?

Coding Agents are fast. But once they become part of a real development workflow, a different set of problems starts to appear:

• Lost progress — After a long session or context reset, neither you nor the Agent can quickly tell what is done, what remains, or what should happen next.
• “Done” without confidence — The Agent reports that the feature works or all tests pass, but you still feel compelled to verify everything yourself.
• Task drift — A clear task gradually turns into something else: an old plan resurfaces, an assumption goes unchallenged, or unrelated work gets pulled in.
• Supervision becomes the bottleneck — Code generation gets faster, while more of your time goes into checking status, reviewing output, correcting direction and asking whether something was actually tested.
• Workflow rules are easy to forget — Important instructions live in CLAUDE.md, AGENTS.md or prompts, but the Agent may still skip a step when the conversation gets long.
• Project memory turns into document sprawl — Plans, handoff notes, memory files and TODO lists keep accumulating, while nobody is entirely sure which version still reflects the project.

Behind all of these problems is a more fundamental question:

When an Agent says “done”, what does “done” actually mean?

Was code written?

Were tests actually run?

Is the current implementation still the one that was verified?

Is the Feature ready to ship?

As coding Agents become faster and more autonomous, generating code is becoming less of the bottleneck. Keeping development continuous, trustworthy and understandable is becoming the harder problem.

That is the problem J4Agent v0.2.0-alpha.1 is designed to address.

---

J4Agent v0.2.0-alpha.1 — A Model Upgrade

v0.2.0-alpha.1 is not simply a larger version of J4Agent v0.1.x.

The development logic has been rebuilt around a different assumption:

An Agent should not merely operate a human-oriented task tracker. The development model itself should be understandable, executable and verifiable by both humans and Agents.

The new Agent-native development journey is:

Requirement
    ↓
 Feature
    ↓
  Work
    ↓
Verification
    ↓
 Release

Each stage represents a different development fact:

• Requirement — what the user actually wants, including how that intent evolves during development.
• Feature — the stable capability or delivery unit used to organize implementation and verification.
• Work — the actual development activity performed on the project.
• Verification — structured evidence that the current implementation has been tested and remains valid for the relevant revision.
• Release — the verified Features intentionally shipped together.

v0.2.0-alpha.1 therefore moves J4Agent away from a Jira-like Work Item model and toward an Agent-native software development fact model.

What changes from v0.1.x?

v0.2.0-alpha.1 is a development-model upgrade, not merely a feature release.

---

Why Agent-native development management?

Traditional issue trackers were designed primarily for humans coordinating humans.

Coding Agents introduce different constraints:

• model context is temporary;
• requirements may evolve while implementation is already underway;
• a natural-language claim of completion is not proof of completion;
• test evidence may become stale after implementation changes;
• large project documents are useful, but continuously injecting them into model context is expensive and error-prone;
• a workflow written in a prompt still depends on the model remembering to follow that prompt.

J4Agent separates reasoning from project facts.

Let models reason. Let J4Agent enforce facts.

Agents remain free to understand requirements, propose solutions, write code, investigate failures and explain trade-offs.

J4Agent maintains the structured state around that work:

• what is being built;
• what changed;
• what remains;
• what was tested;
• which implementation revision was verified;
• what is blocked;
• what can legally happen next.

---

Core development model

1. Requirement — a living user goal

Real requirements rarely stay frozen after the first prompt.

A user may clarify a detail, adjust scope, split a capability or discover a missing condition while development is already underway.

J4Agent models this through Requirement Items:

Requirement
   ├── Requirement Item A ──→ implementation Work
   ├── Requirement Item B ──→ implementation Work
   └── Requirement Item C ──→ implementation Work

Requirement Items can remain active, be superseded by a newer interpretation, or be dropped when they are no longer wanted.

Before a Requirement is considered complete, its active requirement points must be traceable to actual implementation.

A Requirement is intentionally different from a Feature or Release:

• finishing one Feature does not mean the user's Requirement is over;
• shipping one Release does not automatically end the Requirement;
• the Requirement may continue evolving across multiple Features and Releases.

Requirement closure is a human decision.

An Agent may analyze whether the current Requirement appears eligible for closure, but it must not decide on behalf of the user that the product goal is finished.

---

2. Feature — the stable delivery unit

A Feature represents an independently understandable capability that can be implemented, verified and released.

Every active Requirement must have at least one Feature.

Requirements may continue to evolve; Features provide the more stable units around which implementation, verification and release are organized.

---

3. Work — what actually happened

Work describes real development activity, not only a TODO list.

J4Agent distinguishes Work by whether it changes production reality.

Production Work

Examples include:

• implementation code;
• bug fixes;
• dependency changes;
• configuration changes;
• build or pipeline changes;
• migrations and schema changes;
• other release-critical production modifications.

Production Work is release-critical by definition.

Non-production Work

Examples include:

• documentation;
• research;
• planning;
• diagrams;
• other work that does not change production behavior.

This distinction matters because relevant Production Work can invalidate previous Verification.

---

4. Verification — proof about the current implementation

Verification is not just another status field.

A Feature has a persistent Verification gate. TestWork belongs to that Verification and covers relevant Production Work.

A test attempt records structured facts such as:

• the TestWork that was executed;
• the Verification cycle;
• pass or fail result;
• a required summary;
• evidence;
• the Host-observed revision state.

Verification Pass requires current, valid evidence and a structured confirmation flow.

Verification can become stale

A Feature may pass all tests today.

Tomorrow, production code, a dependency, configuration, pipeline or schema may change.

The previous result may no longer prove the new implementation.

Relevant Production Change
          ↓
 Previous Verification
          ↓
         stale
          ↓
 Re-verification required

Verification follows implementation reality.

---

5. Release — what is actually shipped

A Release is an explicit delivery boundary containing verified Features.

Before a Release is ready, J4Agent can evaluate whether:

• included Features have current passed Verification;
• release-critical Production Work is complete;
• relevant revision state is stable and resolved;
• current Verification remains compatible with the release candidate;
• unresolved production or revision facts still block delivery.

A released Feature can later receive maintenance changes through a new maintenance lineage instead of silently rewriting the historical delivery record.

---

Agent guidance: staying on the development journey

Giving an Agent project-management APIs is not enough.

The Agent also needs to understand where it is, what deserves attention and what can happen next without reconstructing the whole project on every tool call.

J4Agent derives lightweight guidance from the current project facts:

Persistent Project Facts
          ↓
Agent Interaction State
     ┌────┴─────┐
     ↓          ↓
Workflow     Continuation
 Brief

Workflow Brief

Workflow Brief is a compact navigation summary.

It can expose:

• the current journey state;
• the current focus;
• the highest-priority attention item;
• the next meaningful step;
• a synchronization hint when project facts may need updating.

It does not create another source of truth. It is derived from the same persistent facts and policy used elsewhere in J4Agent.

When the Agent needs more detail, the Brief can point to read-only Context, Analyze or Help surfaces rather than embedding large explanations into every response.

Continuation

Continuation answers a different question:

What can I actually do next?

It exposes legal next actions and, where J4Agent already knows them, the fixed identifiers or revisions required to continue safely.

The goal is to reduce:

• guesswork;
• invalid tool calls;
• stale revisions;
• workflow drift;
• repeated project-state reconstruction.

A key design principle is:

A workflow should not depend on the Agent remembering to follow a paragraph.

Prompts help the Agent reason. Project facts and policy define the actual development state.

---

Revision-aware development

Verification and Release need to know which implementation state they are evaluating.

J4Agent supports two revision modes.

Local Mode

Local Mode works without Git.

J4Agent observes a stable workspace snapshot over the effective project files and uses that revision identity for Verification and Release checks.

This keeps the complete development journey available for local projects even when Git is not used.

Git Mode

Git Mode can observe repository, worktree, branch, HEAD, dirty state and relevant revision facts.

J4Agent itself is deliberately Git-aware but read-only. Its project-management tools do not proactively perform operations such as:

git add
git commit
git checkout
git switch
git merge
git rebase
git push
git tag
git reset

A development Agent may still use other authorized tools to perform normal Git operations.

The important boundary is that authoritative revision facts come from the Host / Revision Provider, not from the Agent claiming which SHA or working-tree state it believes it tested.

---

Artifact-aware, token-efficient context

Software development produces more than structured lifecycle state.

It also produces long-form knowledge:

Requirement   → intent / requirement documents
Feature       → specification / design
Work          → implementation plans / notes
Verification  → test plans / evidence / reports
Release       → review / release notes

J4Agent does not try to duplicate all of that content inside its database.

Instead:

• structured lifecycle facts live in J4Agent;
• long-form content remains in workspace/repository documents or external references;
• J4Agent stores the relationship between development objects and their Artifacts.

For Agent context, J4Agent favors progressive disclosure.

A linked Artifact can expose a compact brief such as:

Title
Summary
Critical constraints
Link

The Agent reads the full document only when it actually needs the detail.

This keeps context useful without turning the model context window into a second document database.

---

Structured facts, not self-reported confidence

Several principles follow from the v0.2.0-alpha.1 model.

Structured facts are the source of truth

Status, relationships, revision identity, Verification records, Release membership and other lifecycle facts are stored as structured state.

Long-form prose remains useful, but it does not replace those facts.

Unknown means unresolved

Missing information is not silently interpreted as “not implemented”, “safe” or “complete”.

If a fact is required for a Gate and J4Agent does not know it, the fact remains unresolved.

Derived state stays derived

Ready Sets, workflow summaries, compatibility, guidance and other projections are calculated from persistent facts rather than stored as competing sources of truth.

Mutations are explicit and auditable

Agent-facing mutations use idempotent operation identities and revision checks so retries are safe and stale writes can be rejected with recoverable guidance.

Verification history remains history

New test attempts add new Verification Records.

Historical evidence is not rewritten merely because later implementation changes make it stale.

---

Human and Agent authority

Agent-native does not mean “the Agent decides everything.”

J4Agent deliberately separates Agent-operable actions from Host- or human-authoritative facts and decisions.

The goal is human-governed, Agent-operable development management.

---

A typical development journey

For example:

“Add CSV export to the report page.”

J4Agent can organize the work like this:

User intent
   ↓
Requirement
   ├─ initial Requirement Item
   ├─ Feature: CSV export
   └─ pending Verification

Agent clarifies material ambiguity if needed
   ↓
Production Work
   ↓
Implementation
   ↓
TestWork
   ↓
Verification Records + Evidence
   ↓
Revision-aware Verification Pass
   ↓
Release candidate
   ↓
Released Feature
   ↓
Requirement remains open until the human decides
that the overall user goal is actually complete.

During the journey, Context, Analyze, Workflow Brief and Continuation help the Agent understand the current project facts and continue from the correct stage.

---

Project Center

J4Agent provides a DSH-native Project Center for humans to inspect and manage the same development facts used by Agents.

The UI is a review and control surface over the shared model, not a separate human-only project state.

Humans and Agents therefore operate on the same Requirement, Feature, Work, Verification, Release and revision facts instead of maintaining parallel interpretations of the project.

---

Task Graph

Work dependencies are projected into a deterministic Task Graph.

The graph can provide:

• dependency relationships;
• Ready Set projection;
• blocking diagnostics;
• revision-protected dependency mutation;
• a shared execution view for Work scheduling and integration.

The Task Graph is a projection of Work facts, not a separate task database.

---

What J4Agent does not do

J4Agent intentionally keeps its responsibility narrow.

It is not:

• a coding model or coding Agent;
• a guarantee that generated code is correct;
• a replacement for meaningful code review, CI, static analysis or product judgment;
• an autonomous Agent scheduler that spawns workers on its own;
• a remote enterprise issue-tracking service with accounts and RBAC;
• a tool that takes over Git history or automatically commits and pushes code.

J4Agent instead makes the development process around coding Agents more explicit, persistent and verifiable.

It helps turn statements such as implemented, tested, verified and released into inspectable project facts rather than relying only on model self-reporting.

---

Requirements

Current v0.2.0-alpha.1 prerelease baseline:

• Node.js 24
• DeepSeek Harness >=0.1.1-rc.2
• A local DSH Web Profile for the Project Center UI
• J4Agent installed into the Profile where the coding Agent should use its tools

---

Install

Pin the v0.2.0-alpha.1 prerelease tag:

dsh plugin --profile web add github:esonx/dsh-project-j4agent#v0.2.0-alpha.1
dsh web

Or install the tarball attached to the GitHub Release:

dsh plugin --profile web add ./dsh-project-j4agent-0.2.0-alpha.1.tgz
dsh web

See Installation and upgrades for clean-Profile validation, upgrades and uninstall behavior.

---

Get started

1. Start DSH Web and open J4Agent from the sidebar.
2. Initialize the current Workspace and choose Local or Git revision mode.
3. Create a Requirement. J4Agent establishes its initial Requirement Item, Feature and pending Verification structure.
4. Let the Agent create and maintain Work as implementation progresses.
5. Run Verification through TestWork, structured records and current revision evidence.
6. Create a Release when verified Features are ready to ship.
7. Keep the Requirement open until you decide the overall user goal is actually finished.

A J4Agent Project maps to the current DSH Workspace.

---

Agent and DSH integration

J4Agent exposes Agent-facing and Host-facing lifecycle surfaces instead of requiring callers to manipulate its SQLite database directly.

The Agent tool surface covers capabilities such as:

• initializing the current Workspace;
• reading project and journey state;
• retrieving focused development Context;
• analyzing Requirement / Feature / Verification / Release readiness;
• creating and updating development Work;
• recording Verification evidence and confirmation flows;
• managing Artifact links;
• reading and maintaining Task Graph relationships;
• retrieving targeted workflow and command Help.

Exact public tool schemas are versioned with the release and should be treated as the contract.

See Architecture for Host integration details.

---

Data and security boundary

J4Agent stores project-local state under:

<workspace>/j4agent/

including project metadata and the J4Agent SQLite database.

J4Agent does not store model-provider API keys.

The current security boundary is local and trusted-Host oriented. DSH and installed plugins share the Host process, while trusted execution context supplies authoritative actor, session, Workspace and revision facts to J4Agent.

Uninstalling the plugin does not imply deleting project data.

See the Security policy for the supported trust boundary.

---

Upgrading from v0.1.x

[!WARNING] v0.2.0-alpha.1 introduces a breaking development-model upgrade. Back up existing J4Agent project data before upgrading.

The move from the v0.1.x Work Item model to the v0.2.0-alpha.1 Agent-native lifecycle changes both schema and workflow semantics.

Major conceptual changes include:

• Requirement Items and implementation traceability;
• Feature-centered delivery;
• Production vs non-production Work;
• persistent Feature Verification;
• TestWork and append-only Verification Records;
• revision-aware Verification and Release Gates;
• explicit Release membership and candidate state;
• Artifact-linked development context;
• idempotent Agent commands, audit facts and structured continuation.

Before upgrading:

1. Back up the complete <workspace>/j4agent/ directory for every existing project.
2. Read the v0.2.0-alpha.1 release notes and Installation and upgrades.
3. Do not assume a v0.1.x project database can be used directly by v0.2.0-alpha.1 unless the release notes explicitly describe a supported migration path.
4. Validate the upgrade on a non-critical copy before replacing an active project environment.

---

Design principles

The v0.2.0-alpha.1 model is guided by a small set of principles:

1. Development facts over task descriptions Track what is true about the development lifecycle, not only what someone wrote in a ticket.

2. Requirements are living goals User intent may evolve throughout development and should remain traceable to implementation.

3. Feature is the stable delivery unit Work and Verification organize around independently deliverable capabilities.

4. Work describes reality Production-impacting changes are materially different from planning or documentation work.

5. Verification follows implementation reality A passed result is not eternally valid after relevant production changes.

6. Revision is part of the proof Verification and Release must know which implementation state they are evaluating.

7. Structured facts are the source of truth Markdown carries rich content; J4Agent carries lifecycle state, relationships and Gates.

8. Guidance is a projection, not a second state machine Workflow Brief, Continuation and Analyze derive from the same persistent facts and policy.

9. Humans and Agents have different authority Agent-native development remains human-governed where product judgment or Host-observed truth is required.

10. Keep the workflow lightweight; keep delivery Gates strict Day-to-day development can remain flexible while Verification and Release require explicit evidence.

---

Current limitations

v0.2.0-alpha.1 remains intentionally local-first and lightweight.

• No remote multi-user service or enterprise RBAC.
• J4Agent is not an Agent scheduler and does not autonomously spawn workers.
• J4Agent cannot guarantee semantic correctness of generated code; it structures and verifies the development process around that code.
• Local revision mode provides snapshot identity but not Git-style historical attribution.
• Git-aware J4Agent operations are read-only with respect to repository history and branch mutation.
• Long-form Artifact content remains outside the J4Agent database; external Artifacts are linked rather than automatically fetched into model context.

See CHANGELOG.md and the release notes for version-specific limitations.

---

Documentation