# J4Agent

English | [中文](README.zh.md)

**Jira-like Agent-native Project Management for DSH**

J4Agent is a local project-management plugin for DeepSeek Harness. A J4Agent Project is the current DSH Workspace: initialization creates a workspace-local `j4agent/` data directory, then humans, Agents and other DSH plugins share its Work Items, workflow, collaboration, delivery and dependency facts.

Current version: `v0.1.1`

## Highlights

- Jira-like management for each DSH Workspace and five Work Item types: requirement, feature, task, bug and chore.
- Explicit workflow, comments, decisions, milestones, releases and verification records.
- A deterministic Task Graph with dependencies, Ready Set, diagnostics and revision-based conflict protection.
- A workspace-scoped Host service for Workforce and other plugins; callers never access SQLite directly.
- Agent tools for initializing the current Workspace, reading the graph and maintaining dependency edges.
- A DSH-native Project Center dialog for the core human workflow.

## Requirements

- Node.js 24
- DeepSeek Harness `>=0.1.1-rc.2`
- A local DSH Web Profile for the UI; install into the Profile where an Agent should use the tools.

## Install

Pin the release tag:

```bash
dsh plugin --profile web add github:esonx/dsh-project-j4agent#v0.1.1
dsh web
```

Or install the tarball attached to the GitHub Release:

```bash
dsh plugin --profile web add ./dsh-project-j4agent-0.1.1.tgz
dsh web
```

See [Installation and upgrades](docs/INSTALLATION.md) for clean-Profile validation, upgrades and uninstall behavior.

## Get started

1. Start DSH Web and select **J4Agent** in the sidebar.
2. Initialize the current Workspace for J4Agent, then add Work Items and acceptance criteria.
3. Move items through the workflow and record comments or decisions.
4. Use the Task Graph view to inspect dependencies and Ready tasks.
5. Let an Agent use `j4agent_task_graph_read` and `j4agent_task_graph_dependency` when graph work is needed.

## Agent and Workforce integration

The Agent-facing surface is intentionally narrow:

- `j4agent_task_graph_read`: snapshot, task state, Ready Set and diagnostics.
- `j4agent_task_graph_dependency`: idempotently add or remove a dependency using the latest graph revision.
- `j4agent_project_initialize_current`: idempotently initialize the Agent's current DSH Workspace.

Host plugins can call `j4agentProjectWorkspace.ensureProject(workspacePath)` and use the returned Reader/Commands handles. Routed `j4agentTaskGraph*` services remain available for graph integration. See [Architecture](docs/ARCHITECTURE.md).

## Data and security boundary

J4Agent stores `project.json` and `j4agent.sqlite` under `<workspace>/j4agent/`. It does not store model provider keys. The current boundary is local and single-user; DSH and installed plugins share a trusted Host process.

Back up the database before major upgrades. Uninstalling the plugin does not delete it. See the [User guide](docs/USER_GUIDE.md) and [Security policy](SECURITY.md).

## v0.1.1 limitations

- No multi-user accounts, remote service deployment or enterprise RBAC.
- Multi-Agent collaboration facts and Agent references are supported, but J4Agent is not an Agent scheduler and does not spawn or claim workers.
- The Web Task Graph is read-only; dependency mutation is available through trusted Host services and the Agent tool.
- Long-running multi-process stress, online backup/corruption recovery and real remote operating systems are not certified in v0.1.1.

## License

Apache License 2.0. Third-party source and design provenance is recorded in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Maintainer: `esonx`