Workfile

O repositório é o banco de dados.

@illodev/workfile é um protocolo nativo de repositório para coordenar Trabalho, Documentação, Histórico e Memória durável do projeto entre humanos e agentes de software.

Arquivos Markdown no repositório são canônicos. A CLI, a API HTTP e a interface local usam os mesmos serviços centrais, registro de coleções, índice e regras de validação. Nenhum estado exclusivo é mantido no navegador ou em um banco de dados.

Trabalho, Documentação, Histórico e Memória compartilham o índice ProjectRecord comum. O núcleo, a CLI, o servidor HTTP e o runtime MCP são escritos em TypeScript e distribuídos como ESM compilado com declarações públicas. A interface local é pré-compilada e incluída no pacote, e a busca semântica roda no dispositivo por meio do pacote de workspace opcional @illodev/workfile-search-local.

Experimente a demonstração ao vivo — ela reproduz o workspace deste próprio repositório: os cartões reais, lançamentos, incidentes e aprendizados do desenvolvimento do Workfile. Mutações funcionam por sessão de navegador e são redefinidas ao recarregar.

https://github.com/user-attachments/assets/c9cd3035-6729-4cda-9172-984829ab5dbc

Usado por

Em produção

Workfile — dogfooding: cada lançamento é planejado e registrado no próprio .project/

Limites

O Workfile registra trabalho. Ele não configura agentes.

Os dois se confundem porque ambos vivem ao lado do mesmo repositório. Configuradores de ecossistema — gentle-ai é um bom exemplo — instalam uma persona, habilidades selecionadas, roteamento de modelos, servidores MCP e portões de revisão nos agentes que você já usa, em vários agentes ao mesmo tempo. A pergunta deles é como seu agente funciona. A pergunta do Workfile é o que foi feito, quem o detém e com base em quais evidências, e sua resposta são arquivos Markdown que sobrevivem ao agente, à sessão e a este pacote.

Eles se compõem. Um agente bem configurado ainda precisa de um lugar durável para registrar o que fez.

O que está aqui, e não é trabalho de um configurador:

• O repositório é canônico. Um cartão é um arquivo no pull request: revisado no diff, relatado pelo workfile doctor quando malformado. Nenhum estado exclusivo em um navegador, um banco de dados ou ~/.config. Remova o pacote e os registros permanecem legíveis.
• As reivindicações são impostas, não acordadas. A propriedade é verificada na mutação, então um cartão que outro ator detém recusa sua transição com CARD_CLAIM_OWNER_MISMATCH em vez de aceitá-la silenciosamente — uma garantia que nenhuma frase em um prompt pode oferecer.
• review não é done. done exige evidências de algum lugar onde o código realmente executou. Um merge não é evidência.
• Humanos leem os mesmos registros. A interface, o changelog renderizado e os lançamentos são derivados exatamente do que o agente escreve; não há uma visão de máquina e uma visão humana para manter em sincronia.

O que está deliberadamente ausente: o Workfile não instala ou atualiza agentes, não fornece uma persona, não roteia modelos nem seleciona um catálogo de habilidades. Ele sincroniza seu próprio protocolo nos arquivos de instrução que um agente já lê (workfile agents sync) e expõe cada operação via MCP — neutro em relação a fornecedores, mas um servidor, não um ecossistema.

Requisitos

• Node.js 22 ou mais recente.
• npm, pnpm, yarn ou Bun podem invocar o pacote.

Instalação

Todo comando workfile … neste README exige que o pacote esteja instalado — execuções únicas de pnpm dlx / npx rodam um comando e descartam o binário em seguida:

pnpm add -D @illodev/workfile     # per repository (recommended)
pnpm workfile doctor              # dependency bins run through pnpm / npx

pnpm add -g @illodev/workfile     # or globally: `workfile` lands on your PATH
workfile doctor
wf doctor                         # `wf` is the same binary, for typing by hand

wf é um alias, não uma renomeação: ambos os nomes alcançam o mesmo ponto de entrada, e as dicas de ajuda e erro respondem naquele que você digitou. Mantenha a forma longa em qualquer coisa gerada ou compartilhada. wf só resolve depois que o pacote está instalado, e existe um wf não relacionado no registro — então npx wf buscaria a ferramenta de outra pessoa onde npx workfile falha diretamente.

pnpm dlx @illodev/workfile init é adequado para inicialização única, mas mantenha o pacote como devDependency depois: é isso que faz os scripts project* que init adiciona ao package.json resolverem. Esse prefixo é um namespace de script npm — pnpm project opens the UI, pnpm project:doctor executa as verificações — e não tem nada a ver com o nome antigo do binário.

API TypeScript

A superfície publicada expõe JavaScript e declarações por meio de exports condicionais de pacote. Consumidores TypeScript recebem contratos tipados de configuração, workspace, registro, busca e integração do pacote raiz e de cada subcaminho documentado:

import {
    defineProject,
    type CardStatus,
    type ProjectConfig,
    type ProjectRecord
} from "@illodev/workfile";
import { createSemanticSearchProvider } from "@illodev/workfile/search";

const config: ProjectConfig = defineProject({
    schemaVersion: 2,
    name: "Billing",
    cards: {
        areas: ["api", "web"]
    }
});

const status: CardStatus = "doing";

A CLI e a interface não exigem TypeScript nos projetos consumidores. React, Primer, Vite e os pacotes de tipos da interface são dependências apenas de build; o pacote instalado serve assets de navegador empacotados de dist/ui.

Workspace

Um projeto é descoberto por meio de project.config.mjs e normalmente armazena arquivos de propriedade do protocolo sob .project/:

project.config.mjs
.project/
├── VERSION
├── cards/
│   └── archive/
├── assets/
├── docs/
├── changelog/
│   ├── unreleased/
│   └── releases/
├── memory/
│   ├── learnings/
│   ├── decisions/
│   ├── incidents/
│   ├── conventions/
│   └── context/
├── agents/
└── .cache/

Configuração mínima — um objeto simples, não defineProject(...). O carregador aplica defineProject por conta própria, e um import aqui é um especificador nu que o arquivo só pode resolver com node_modules presente, o que quebra os dois consumidores que rodam sem um: um workspace inicializado por pnpm dlx antes de o pacote ser instalado, e a execução de npx do job de CI gerado em um clone limpo. A anotação JSDoc mantém a tipagem do editor sem um import em runtime:

/** @type {import("@illodev/workfile").ProjectConfigInput} */
export default {
    schemaVersion: 2,
    name: "My project",
    cards: {
        areas: ["api", "web", "infra", "docs"]
    },
    docs: {
        sources: [
            "README.md",
            "docs/**/*.md",
            "apps/*/README.md",
            ".project/specs/**/*.md"
        ]
    },
    changelog: {
        releaseStrategy: "semver",
        defaultVisibility: "public"
    },
    memory: {
        collections: [
            "learnings",
            "decisions",
            "incidents",
            "conventions",
            "context"
        ]
    },
    agents: {
        targets: ["agents-md", "cursor"]
    },
    ci: {
        targets: ["github"]
    },
    mcp: {
        allowMutations: true
    },
    search: {
        semanticWeight: 0.35,
        maxProviderRecords: 500
    }
};

Áreas, caminhos e vocabulários específicos do projeto são resolvidos em runtime e expostos por meio do esquema efetivo. Os oito status de Trabalho e as semânticas da coleção de memória do schema-v2 permanecem contratos do protocolo.

Trabalho

Cartões são registros Markdown gerenciados sob .project/cards/. O módulo de Trabalho fornece hierarquia, dependências, reivindicações, escopo, transições de status, arquivos, assets e gravações cientes de conflitos.

workfile card list --json
workfile card show T-0042 --json
workfile card create --title "Implement runtime schema" --area infra
workfile card create --json-input card.json   # body, parent, source and tags in one call
workfile card claim T-0042 --scope apps/api,packages/sdk   # actor resolves itself
workfile card transition T-0042 review
workfile card patch T-0042 --json-input changes.json --expected-revision sha256:...
workfile card archive T-0042
workfile card reopen T-0042 --status backlog

Documentação

Documentação combina duas fontes sem copiar documentação existente:

• Documentos indexados descobertos a partir de globs configurados. Eles recebem IDs PATH-* determinísticos e permanecem somente leitura por meio do protocolo.
• Documentos gerenciados armazenados em .project/docs/ com IDs DOC-NNNN estáveis, frontmatter tipado e mutações cientes de revisão.

Documentos gerenciados são lidos recursivamente, então podem ser agrupados em pastas — incluindo pastas que você cria manualmente. IDs permanecem globais e sequenciais: uma pasta é organização, não identidade. Novos documentos seguem docs.layout (kind, o padrão, os agrupa por tipo de documento; flat os escreve na raiz gerenciada) e --folder o substitui.

workfile doc list --query billing
workfile doc show DOC-0012 --json
workfile doc create --title "Deployment runbook" --kind runbook --status current
workfile doc create --title "Rate limiting" --folder architecture/billing
workfile doc move DOC-0012 --folder architecture
workfile doc patch DOC-0012 --json-input changes.json --expected-revision sha256:...

O doctor detecta links locais quebrados, registros relacionados ou substituídos não resolvidos, caminhos de escopo ausentes e relações de revisão/fonte desatualizadas.

Histórico

Histórico usa fragmentos de mudança atômicos em vez de pedir a vários branches ou agentes que editem um único CHANGELOG.md compartilhado.

Fragmento não lançado:

---
id: CHG-0042
title: Add portable history workspace
type: added
area: infra
visibility: public
cards: [T-0042]
created: 2026-07-28
updated: 2026-07-28
---

Um lançamento consome fragmentos selecionados, move-os para o diretório de lançamento e cria um registro REL-NNNN canônico. Changelogs públicos ou internos são saída derivada.

workfile changelog list --unreleased
workfile changelog add --title "Add portable history" --type added --area infra
workfile changelog preview
workfile changelog release 0.4.0 --title "History and Memory"
workfile changelog render --visibility public
workfile changelog render --visibility public --write
workfile changelog verify

Versões de lançamento podem usar validação semver, calendar ou freeform de acordo com a configuração. Fragmentos e lançamentos participam da mesma busca do workfile e do grafo de backlinks que cartões, documentos e memória.

Memória

Memória é um conjunto de registros tipados, atômicos e cientes de ciclo de vida, em vez de uma única transcrição de conversa crescente:

Coleção	Prefixo	Propósito
Aprendizados	LRN	Observações reutilizáveis com sinais de confiança e ocorrência
Decisões	ADR	Decisões propostas, aceitas, rejeitadas ou substituídas
Incidentes	INC	Eventos operacionais, gravidade, tempo e ações corretivas
Convenções	CONV	Regras duráveis seguidas por humanos e agentes
Contexto	CTX	Estado de projeto útil, mas potencialmente expirável

workfile memory list --collection learnings --status active
workfile memory add learning --title "Atomic fragments avoid merge conflicts" \
  --confidence high
workfile memory add decision --title "Keep Markdown canonical" --status accepted
workfile memory add incident --title "Release pipeline stalled" --severity high
workfile memory graduate LRN-0004 --to CONV-0002,DOC-0012
workfile memory supersede ADR-0003 --by ADR-0009
workfile memory patch CTX-0002 --json-input changes.json --expected-revision sha256:...
workfile memory verify

O doctor verifica estados de ciclo de vida inválidos, alvos de graduação/substituição ausentes, contexto expirado e metadados de resolução de incidentes incompletos.

Índice unificado

Cada módulo normaliza seus arquivos como entradas ProjectRecord por meio de um registro de coleções comum. O índice derivado do processo local fornece:

• busca textual ponderada em todo o projeto;
• consulta por ID de registro estável;
• referências de saída e backlinks de entrada em todos os quatro domínios;
• links de cartão source: e links Markdown locais;
• sinais de saúde, ciclo de vida e atualização específicos do módulo;
• contagens de módulos e coleções.

O estado canônico sempre permanece no disco. O cache do servidor é de curta duração, invalidável e totalmente reconstruível.

workfile search "billing architecture"
workfile search release --kind change,release,memory --limit 25 --json

Inicialização

O inicializador pode rodar interativamente ou deterministicamente em automação. Ele detecta o gerenciador de pacotes, pastas de monorepo, áreas prováveis de cartões, fontes de documentação, ambientes de agentes existentes e provedores de CI. Uma execução de teste expõe o plano exato do sistema de arquivos.

pnpm dlx @illodev/workfile init
pnpm dlx @illodev/workfile init --yes \
  --agents agents-md,claude,cursor,copilot --ci github
workfile init --dry-run --json

O project.config.mjs gerado exporta um objeto simples, então um workspace inicializado via pnpm dlx permanece carregável antes de o pacote ser instalado localmente. Arquivos existentes não são sobrescritos a menos que --force seja explícito. .project/.cache/ é adicionado a .gitignore; todos os arquivos canônicos do protocolo permanecem rastreados.

Demonstração hospedada

A interface inclui um modo de demonstração para hospedagem estática (Vercel, GitHub Pages, qualquer servidor de arquivos). npm run build:demo compila a interface com uma API em memória que reproduz um snapshot de um workspace semeado: cada visualização funciona e as mutações se comportam normalmente para a sessão, depois são redefinidas ao recarregar. O repositório inclui um vercel.json, então importá-lo no Vercel implanta a demonstração com zero configuração.

pnpm run demo:data   # reseed and resnapshot packages/workfile/ui/src/demo-data.json
pnpm run build:demo  # static demo build into packages/workfile/dist/demo

Builds regulares removem a camada de demonstração e o snapshot do bundle.

Lançamento

Lançamentos publicam a partir do CI via npm publicação confiável (OIDC) — nenhum token npm é armazenado no repositório. Antes de cortar, se qualquer mudança de interface foi enviada desde a última tag, execute pnpm run screenshots: ele recaptura cada visualização e publica as imagens do README e da página de destino por conta própria, e elas pertencem ao commit que moveu o shell, não ao bump de versão. O circuito:

1. Corte o changelog: workfile changelog release <version> e workfile changelog render --write.
2. Bump e tag: npm version <version> e depois git push && git push --tags. O hook de versão carrega cada pacote packages/* dentro do mesmo bump — pacotes de workspace sempre enviam a versão do núcleo.
3. O workflow Release verifica se a tag corresponde a package.json (e que nenhuma versão de workspace divergiu), executa check:release (build, typechecks, testes, auditoria e um smoke de tarball empacotado) com pnpm, e publica o núcleo e cada pacote de workspace com a CLI npm sob latest.

Não há canal de pré-lançamento: cada versão publicada está a um npm install de distância, e uma tag v*-rc.* falha o lançamento em vez de publicar. Isso é uma consequência da publicação confiável, não uma preferência — OIDC autoriza npm publish e nenhuma outra gravação de registro, então o CI não pode mover uma dist-tag de um candidato a lançamento depois que ele foi definido.

Protocolo do Agente

Instruções canônicas e workflows vivem sob .project/agents/. Blocos gerenciados compactos são sincronizados em ambientes suportados sem substituir conteúdo de usuário não relacionado:

AGENTS.md
CLAUDE.md
.cursor/rules/workfile.mdc
.github/copilot-instructions.md

workfile agents sync
workfile agents sync --targets agents-md,claude,cursor,copilot
workfile agents check
workfile agents context --card T-0042

Blocos gerenciados carregam a versão do pacote e um digest SHA-256. agents check e workfile doctor relatam instruções geradas ausentes, não gerenciadas ou desatualizadas. O contexto do agente é limitado e prioriza o cartão selecionado, relacionamentos diretos, convenções ativas, incidentes não resolvidos e contexto não expirado, em vez de carregar toda a memória do workfile.

Model Context Protocol

O Workfile inclui um servidor MCP local, sem dependências, usando JSON-RPC delimitado por nova linha em UTF-8 sobre stdio. Ele delega cada operação aos mesmos serviços centrais usados pela CLI e pela API HTTP, fala tanto a revisão moderna (2026-07-28) quanto a legada (2025-11-25) do protocolo, e expõe 32 ferramentas, quatro recursos e três prompts. Ferramentas de mutação desaparecem completamente no modo --read-only.

Aponte um cliente para ele sem instalar nada. Esta é a invocação que o registro oficial publica para io.github.illodev/workfile, e o que a maioria dos clientes construirá para você a partir dessa listagem:

{
  "mcpServers": {
    "workfile": {
      "command": "npx",
      "args": ["-y", "@illodev/workfile", "mcp"]
    }
  }
}

mcp há um subcomando, não um binário: npx resolve o binário cujo nome corresponde ao pacote e entrega a ele tudo o que vier em seguida. Acrescente --root PATH quando o cliente iniciar em um local diferente do workspace — ele procura para cima por .project/ caso contrário — e --read-only para servir apenas as ferramentas de leitura, com toda mutação recusada.

Com o pacote instalado, o mesmo servidor está a um subcomando de distância:

workfile mcp
workfile mcp inspect --json
workfile mcp config --read-only --json

Para o Claude Code, a mesma superfície é fornecida como um plugin — o servidor MCP mais os comandos /claim, /card-context, /next e /done, uma skill e hooks que transformam reivindicações de cartões em uma proteção executável — sem arquivos gerados commitados no repositório:

/plugin marketplace add illodev/workfile
/plugin install workfile@illodev

O contrato completo — inventário de ferramentas, recursos, prompts, higiene de processos e a superfície do plugin — está documentado em docs/mcp.md.

O servidor está listado no Glama, que o constrói em um contêiner e inspeciona os recursos que ele relata:

Integrações de busca

A busca lexical permanece determinística e local. Hosts podem injetar um provedor semântico opcional programaticamente; o Workfile nunca seleciona um fornecedor nem envia conteúdo do repositório pela rede por conta própria.

Primeira parte: embeddings locais

@illodev/workfile-search-local executa embeddings no dispositivo (onnxruntime-web, ONNX em CPU, Xenova/multilingual-e5-small quantizado) — o conteúdo do repositório nunca sai da máquina. Declare-o em project.config.mjs com um import protegido, porque a configuração também deve carregar onde o pacote não pode resolver (o job de CI gerado executa npx em um clone limpo):

export const integrations = await (async () => {
    try {
        const { localSearchIntegration } = await import(
            "@illodev/workfile-search-local"
        );
        return [localSearchIntegration()];
    } catch {
        return []; // package absent: search stays lexical
    }
})();

export default {
    // …
    search: { provider: "local-embeddings" }
};

Conheça o modelo de custo antes de conectá-lo: a primeira busca híbrida incorpora cada registro candidato não armazenado em cache — minutos de CPU sustentada em um workspace de alguns milhares de registros, acionado pela superfície que buscar primeiro (CLI, interface do board ou o servidor MCP que um agente carrega). O provedor limita o ONNX a metade dos núcleos por padrão, persiste por lote para que uma passagem interrompida seja retomada em vez de recomeçar, e relata o progresso no stderr; dimensionar search.maxProviderRecords para o seu corpus torna cada registro elegível. Detalhes e opções em packages/search-local/README.md.

Traga o seu próprio

import {
    createSemanticSearchProvider,
    searchProjectRecordsHybrid
} from "@illodev/workfile/search";

const provider = createSemanticSearchProvider({
    id: "company-embeddings",
    async search({ query, records }) {
        // Return [{ id, score }] with scores between 0 and 1.
        return rankWithYourApprovedProvider(query, records);
    }
});

const result = await searchProjectRecordsHybrid(index.records, query, {
    provider,
    semanticWeight: 0.35
});

O limite do adaptador torna a divulgação externa de dados uma decisão explícita do host e mantém a implementação canônica de Markdown/índice independente de fornecedor.

Registro de integração experimental

Hosts programáticos podem agrupar adaptadores aprovados de busca semântica e saúde em um pequeno registro neutro em relação a fornecedores:

import {
    createIntegrationRegistry,
    defineProjectIntegration
} from "@illodev/workfile/integrations";

const integrations = createIntegrationRegistry([
    defineProjectIntegration({
        id: "company.platform",
        semanticSearchProvider: provider,
        async healthCheck({ workspace, index }) {
            return [];
        }
    })
]);

O registro é aceito pelo servidor MCP e pelas APIs do doctor. Ele é intencionalmente limitado no RC atual: rastreadores de problemas específicos de fornecedores, sistemas de implantação e credenciais não fazem parte do pacote canônico. O limite pode amadurecer a partir de integrações reais sem comprometer o esquema com GitHub, GitLab, Jira ou um provedor de implantação.

Modelos de CI

Os arquivos de CI usam o mesmo contrato de arquivos gerenciados e podem ser gerados para GitHub Actions, GitLab CI ou um runner de shell genérico:

workfile ci sync --targets github,gitlab,generic
workfile ci check

Os modelos executam tanto o doctor do workfile quanto a verificação de sincronização do agente contra a versão fixada do Workfile.

Migração legada

O sistema v1 .planning pode ser planejado e aplicado com verificações determinísticas de colisão:

workfile migrate plan --source .planning
workfile migrate apply --source .planning --mode copy
workfile migrate apply --source .planning --mode move

Cartões e ativos legados válidos tornam-se registros de Trabalho v2 canônicos. Propostas antigas, changelogs, aprendizados e registros malformados são preservados sob .project/sources/legacy-planning/ em vez de serem silenciosamente reinterpretados com um esquema incompatível. Cada migração aplicada escreve .project/migrations/legacy-planning.json com origem, destino, digest e metadados de resultado.

CLI geral

workfile init
workfile schema --json
workfile doctor --json
workfile ui
workfile ui --read-only --host 0.0.0.0 --allowed-host board.example.com

Os comandos retornam erros estáveis legíveis por máquina com --json. Uma revisão desatualizada sai com código 3; erros de configuração saem com código 2; erros de validação e não encontrado saem com código 1. A superfície completa de comandos está documentada em docs/cli.md.

API HTTP

workfile ui --read-only --host 0.0.0.0 --allowed-host board.example.com serve o mesmo board como uma coisa que as pessoas leem: toda rota de mutação responde 409 WORKSPACE_READ_ONLY e a interface remove seus recursos de edição. Ainda não há autenticação própria, então coloque um proxy reverso que autentique na frente de qualquer coisa publicada dessa forma — veja docs/security.md.

workfile ui inicia o servidor local, normalmente em http://127.0.0.1:4747. A superfície versionada /api/v2/* cobre o workspace, busca unificada e todas as coleções — cartões, docs, changelog (incluindo pré-visualização/montagem/renderização de release), ciclo de vida da memória, agentes e sincronização de CI. Leituras de registros gerenciados expõem um ETag, gravações aceitam If-Match e erros usam códigos estáveis. A referência de endpoints vive em docs/http-api.md.

Interface local

A navegação é uma barra lateral recolhível agrupada por domínio:

• Trabalho: Explorer, Triage, Flow, Epics e uma Linha do Tempo Gantt (barras coloridas por status, escala mensal, marcador de hoje).
• Conhecimento: Docs (busca, Markdown, metadados, frescor, escopo, backlinks) e Memória (coleções tipadas, avisos de ciclo de vida, graduação e substituição).
• Projeto: Workflow (o grafo de proveniência — cada registro um nó, relações tipadas como arestas), Histórico (fragmentos, releases, preparação de release, pré-visualização do changelog renderizado) e Saúde.

Problemas de saúde podem navegar para registros em qualquer domínio. A configuração em tempo de execução direciona áreas de cartões, vocabulários de mudança e status de coleções de memória; esses valores não são compilados nas visualizações. Links de arquivos abrem o editor local, ou a interface web do repositório quando o servidor fornece um repoUrl (como a demonstração hospedada faz).

A Visão Geral responde "como estamos indo" em uma frase escolhida do pior para o melhor — erros do doctor, reivindicações pendentes, escopos em colisão, cartões bloqueados, trabalho em andamento — acima do rastro de cada movimento que os agentes escreveram enquanto você estava ausente.

Explorer com o inspetor aberto	Linha do tempo Gantt

Histórico com releases	Memória (tema escuro)

O Workflow lê as coleções em um único grafo em vez de quatro listas: a primeira linha de alternâncias as seleciona, a segunda seleciona os tipos de relação. Uma relação declarada no frontmatter desenha uma aresta sólida e um ID escrito em uma frase uma tracejada, porque um link em prosa é uma afirmação mais fraca do que um campo e não deve parecer igualmente sólido. A varredura de prosa está desativada por padrão — são 294 das 742 arestas deste workspace. A imagem acima é o corpus curado com suas relações declaradas: um doc related ao cartão que ele rastreia, um aprendizado ao incidente que o ensinou, uma decisão ao cartão que ele resolveu — então um cartão, a decisão por trás dele e o doc que o descreve leem como um único objeto.

Desenvolvimento

O repositório é um workspace pnpm: a raiz é um shell privado que contém a versão e scripts delegadores, enquanto tudo publicado vive sob packages/ — o núcleo em packages/workfile, provedores como packages/search-local ao lado dele, todos enviados em sincronia de versão. O pnpm é fixado via o campo packageManager (corepack enable o pega automaticamente):

pnpm install
pnpm run check
pnpm run smoke:package
node ./packages/workfile/dist/bin/workfile.js mcp inspect --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js schema --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js doctor --root ./packages/workfile/test/fixtures/workspace --json
node ./packages/workfile/dist/bin/workfile.js ui --root ./packages/workfile/test/fixtures/workspace

pnpm run check compila o runtime TypeScript e as declarações, verifica o contrato estrito de consumidor público, verifica tipos e empacota a interface React, e executa a suíte de testes completa. pnpm run smoke:package empacota e instala o tarball real em um projeto temporário antes de exercitar a inicialização, todos os quatro domínios, MCP e a interface empacotada — as instalações de fumaça usam npm de propósito, exercitando o caminho do consumidor npm.

prepack reconstrói as declarações de runtime e a interface para que um pacote publicado futuro contenha apenas artefatos de runtime compilados sob dist/, nunca TypeScript de desenvolvimento ou uma árvore de fonte de interface copiada.

Garantias atuais

• codec de frontmatter restrito com idas e voltas estáveis de escalar/lista em bytes;
• preservação de campos de frontmatter desconhecidos e bytes do corpo;
• substituição atômica de arquivos, bloqueios por registro e reservas de ID seguras contra colisão;
• tokens de revisão SHA-256 e rejeição de gravação desatualizada;
• operações atômicas de reivindicação, transição, arquivamento e reabertura de Trabalho;
• mutações gerenciadas de Docs, fragmentos de Histórico e Memória tipada;
• montagem de release com consumo canônico de fragmentos e renderização derivada;
• caminhos seguros configuráveis para o repositório e vocabulários de runtime;
• normalização comum, busca, referências e backlinks em todos os domínios;
• diagnósticos de saúde para Trabalho, Docs, Histórico e Memória;
• ESM compilado e declarações .d.ts para o pacote público e exportações de subcaminho;
• binários executáveis empacotados de CLI/MCP verificados a partir de uma instalação limpa de tarball;
• API versionada mais um adaptador de compatibilidade para o board original.

Documentos

• docs/getting-started.md — instalação, inicialização e o ciclo diário.
• docs/cli.md — referência completa da CLI para cada módulo.
• docs/http-api.md — referência de endpoints, convenções e erros.
• docs/mcp.md — contrato do servidor MCP: ferramentas, recursos, prompts.
• docs/security.md — modelo de ameaças do servidor local, guarda de requisições, manipulação de ativos e o que está deliberadamente fora do escopo.
• docs/ui.md — a interface: sua construção, a garantia de zero dependências e como a migração shadcn coexiste com o sistema de design.
• docs/SPEC.md — a especificação normativa do protocolo: modelo de dados, contratos de registro, semântica de revisão e o contrato de integração MCP.