Docs UI

Local-first spreadsheet editor and repo-scoped agent workflow for structured Markdown project documentation. It runs on a separate localhost port and reads or writes the real files in the selected project.

Requirements

• Node.js 20 or newer
• A local project directory with write permission

Quick Start

Run from the root of a project:

npx skillify-docs-ui

The command creates missing workflow files, starts the server, and prints the local URL:

Docs UI: http://127.0.0.1:5137

The UI is served at /. It is not added to the project's backend, frontend, Docker image, or deployment routes.

On startup, the CLI checks npm for a newer published version and prints the update command when one exists. Disable this best-effort check with DOCSUI_NO_UPDATE_CHECK=1.

Generated Files

The first run creates only the agent workflow files without replacing existing content:

AGENTS.md
.agents/
└── skills/
    ├── api-contract-backend-architect/
    ├── erd-db-architect/
    ├── feature-spec/
    ├── product-discovery-ba/
    ├── project-discovery/
    ├── review-techlead/
    ├── scrum-orchestrator/
    ├── sdd-techlead/
    ├── srs-ba/
    ├── technical-research-architect/
    ├── test-qa/
    ├── ui-wireframe-designer/
    └── webapp-testing/

The CLI does not create docs/ automatically. Ask the agent workflow to create the needed docs when product work requires them; each owning skill has its document template under its local assets/ folder. docs/wireframe.md is used only for UI-affecting PBIs after the UI direction is proposed and confirmed. docs/specs/ receives one FEAT-###.md context package only after a feature is selected into a Sprint. Codex discovers repo skills from .agents/skills/; restart an existing Codex session if newly scaffolded skills do not appear immediately.

Inside this repository, scaffold sources live under AGENTS_tmp.md and .agents_tmp/skills/ so the workflow is packaged for target projects without becoming the active workflow for developing docsui itself. When docsui runs in another project, it creates AGENTS.md and .agents/skills in that project. Document scaffolds live beside their owning skills in assets/.

Agent Workflow

$scrum-orchestrator is the single entry point for meaningful work. It detects greenfield, undocumented legacy, or established-project context and routes only affected specialists:

Discovery/learning -> Product Goal -> Ordered Product Backlog
                   -> Refinement -> READY
                   -> Sprint Planning (WHY / WHAT / HOW)
                   -> technical research / UI wireframe when needed
                   -> Sprint Goal + Selected PBIs
                   -> implementation + continuous verification
                   -> code review + DoD -> Increment
                   -> Sprint Review feedback -> adapted backlog

New requests default to the Product Backlog, not the current Sprint. Supporting documents evolve just in time; they are not a fixed SRS-to-design-to-code pipeline. AGENTS.md defines routing, Sprint rules, specialist ownership, and the Done gate.

Initializing documents does not seed sample PBIs. In legacy projects, baseline discovery scans the whole repository and writes AS-IS knowledge to docs, but discovery itself is not added to the Product Backlog. For feature work, agents read the full Product Backlog before design/implementation so known future PBIs influence extension points without building unselected scope.

Commands

Create only missing AGENTS.md and .agents/skills files:

npx skillify-docs-ui init

Preview and update workflow files from the installed package:

npx skillify-docs-ui sync

sync shows files to create or update and asks for confirmation before overwriting AGENTS.md or .agents/skills/**.

Start the editor and create missing workflow files automatically:

npx skillify-docs-ui

Start explicitly on another port or directory:

npx skillify-docs-ui serve --root ./my-project --docs documentation --port 4310

Overwrite all scaffold files intentionally:

npx skillify-docs-ui init --force

Available options:

| Option | Default | Purpose | |---|---|---| | --root <path> | Current directory | Project root where AGENTS.md and .agents/skills are created. | | --docs <path> | docs | Markdown directory to read and edit, relative to root or absolute. | | --port <number> | 5137 | Local editor port. | | --host <host> | 127.0.0.1 | Bind address. Keep the default for local-only access. | | --no-init | Disabled | Start without creating missing workflow files. | | --force | Disabled | Overwrite scaffold files; available only for init. |

Local Synchronization

There is no copy of the documents inside the UI. The Node server reads and writes the selected host directory directly:

• An agent or editor changes a Markdown file: the worksheet refreshes within about two seconds.
• The browser saves a worksheet: the Markdown file changes on disk immediately.
• Both change the same file: the browser detects the revision mismatch and requires a reload instead of silently overwriting disk content.

Writes use a temporary file and atomic rename. API requests can access only the eight configured worksheet filenames; feature specs remain normal Markdown files managed by the feature-spec skill.

Install In A Project

For a pinned development dependency:

npm install --save-dev skillify-docs-ui
npx skillify-docs-ui

After installing globally:

npm install -g skillify-docs-ui
docsui
docsui init

Installing the dependency alone does not write into the project. Scaffolding happens when the CLI is executed, because npm lifecycle scripts do not provide a reliable or safe target project directory.

Markdown Contract

The editor modifies the first GFM table in each document and preserves content before and after that table. Keep the existing columns stable. Multiline UI values are serialized with <br> so each record remains one Markdown table row.

Security

The server binds to 127.0.0.1 by default, uses a strict file allowlist, caps documents at 2 MB, validates row dimensions, and sends restrictive browser security headers. Do not bind to 0.0.0.0 unless access from other machines is intentional and protected by the local network.