Superficie per agenti e sviluppatori

Deep Work Plan per sviluppatori e agenti AI

deepworkplan.com pubblica una superficie leggibile dalle macchine accanto alle proprie pagine: un’API per agenti descritta con OpenAPI, un server MCP senza stato, mirror nativi in Markdown di ogni pagina in 17 lingue e la skill DWP installabile. Tutto in questa pagina è attivo, pubblico e gratuito — non c’è nulla per cui registrarsi.

Senza autenticazione per scelta progettuale

Non ci sono chiavi API da generare, nessuna danza di OAuth e nessun sandbox separato dalla produzione — è la superficie di produzione stessa a fare da sandbox. È una proprietà deliberata della metodologia: gli agenti non possono compilare moduli «contatta le vendite», quindi il sito non ne chiede mai uno.

Sola lettura

Ogni operazione è un GET sicuro e memorizzabile in cache — tranne l’endpoint MCP, che è POST. Non esistono operazioni di scrittura, upload né cambi di stato da nessuna parte.

Nessuna chiave API

Nessuna registrazione, nessun token, nessun livello di rate limit. L’accesso anonimo è il contratto documentato, dichiarato in /auth.md e negli stub di discovery di OAuth.

Gratuito e open source

I contenuti del sito e la skill DWP sono sotto licenza MIT. Li usi in lavori commerciali e non commerciali senza chiedere permesso.

Orientato alle macchine

Errori JSON strutturati sui percorsi /api, corpi di recupero 404 in Markdown, catalogo API RFC 9727 e un manifest di capacità ARD — costruito per il consumo da parte degli agenti.

Pianificare ed eseguire con la skill

L’API sopra permette a un agente di leggere questo sito. La skill DWP è ciò che permette a un agente di eseguire la metodologia — installatela una volta in un repository e fornisce un router più nove sub-skill, invocate come comandi slash (o per nome, per gli agenti che intercettano lo slash — la maggior parte usa # al suo posto, ad esempio #dwp-execute).

Due scelte indipendenti: il formato e quanta revisione volete

Ogni piano sceglie un valore per ciascun asse. Sono indipendenti — un piano Lite può funzionare in trust, un piano Full può funzionare in guided, ed entrambi possono cambiare modalità in seguito senza cambiare formato.

Lite

I record dei task vivono in linea nel README del piano, dietro ancore stabili #task-N — nessun file di task separato. Pensato per lavoro piccolo e delimitato: una sola questione, circa una sessione. Comunque un piano completo: id di task stabili, una Touched Surface, criteri di accettazione, un validation gate e un Final Review — mai una bozza ridotta.

Full

Un file per task sotto N.task_<slug>.md, per lavoro a lungo termine che si estende su ore o giorni, o quando un piano ha vere dipendenze tra i task. Un piano Lite viene promosso a Full in seguito con /dwp-refine promote quando i record compatti non bastano più — la promozione non riesegue mai il lavoro concluso.

Guided (predefinito)

dwp-create analizza l’obiettivo, lo scompone e materializza un piano revisionabile — già il piano reale ed eseguibile, mai una bozza usa e getta — poi chiede: mantenerlo, promuovere Lite a Full, modificarlo o fermarsi. Una persona resta nel loop prima che inizi qualsiasi lavoro sul prodotto. Consigliato le prime volte, o per tutto ciò che ha una posta in gioco più alta.

Trust (o auto)

Aggiungete trust (o auto) come ultima parola — ad esempio /dwp-create <goal> trust — e l’agente salta il giro di revisione, materializza un piano preapprovato e restituisce direttamente il comando di esecuzione. La scorciatoia per utenti esperti una volta che vi fidate del flusso; registra comunque ogni decisione e gate, semplicemente non si ferma a chiedere.

Le nove sub-skill

Ogni sub-skill viene invocata come comando slash all’interno del repository che ha installato la skill — non contro questo sito web. Il riferimento completo per ciascuna vive nel catalogo del kit.

Le nove sub-skill
`/dwp-create <goal>`	Trasforma un obiettivo in un piano — Lite per impostazione predefinita, Full per lavoro più grande, entrambe le modalità dalla tabella sopra.
`/dwp-execute`	Esegue un piano esistente task per task: lo legge integralmente, esegue ogni task in ordine, valida il suo gate, aggiorna l’avanzamento.
`/dwp-refine`	Aggiunge, rimuove o riordina i task in un piano esistente preservando il lavoro completato e le sue evidenze registrate.
`/dwp-resume`	Ricostruisce lo stato dai file stessi del piano e continua un piano interrotto dal suo primo task incompleto.
`/dwp-status`	Riporta l’avanzamento di un piano — task completati, in corso, in sospeso — senza apportare alcuna modifica.
`/dwp-verify`	Verifica, meccanicamente, se il repository è AI-first e se i suoi piani sono ben formati. Non cambia nulla; riporta superato o non superato.
`/deepworkplan-onboard`	Rende un repository AI-first: ragiona sul suo stack, poi genera un AGENTS.md adattato, docs/, .agents/ e un .dwp/ escluso da git.
`/skill-create, /agent-create`	La sub-skill autrice: fa crescere il kit proprio del repository — una skill riutilizzabile per una procedura ripetibile, o un agente per un ruolo ricorrente con il proprio modello e i propri strumenti.
`/dwp-upgrade`	Verifica se esiste una release più recente della skill pubblicata e, solo dopo approvazione esplicita, la installa e riesegue l’onboarding come un passaggio nuovo — ogni piano in corso sotto .dwp/ resta intatto.

Due modi per eseguirla

La stessa skill, gli stessi nove comandi — il formato e la modalità di revisione cambiano con la dimensione e la posta in gioco del lavoro, non con lo strumento.

Una correzione piccola e delimitata — Lite, trust

Una sola questione, circa una sessione, posta in gioco bassa: saltare il giro di revisione e lasciare che l’agente materializzi ed esegua direttamente un piano Lite.

Terminale — comandi slash

# A small, bounded fix: skip the review round, run it directly.
/dwp-create fix the flaky checkout test trust
/dwp-execute

Lavoro a lungo termine — Full, guided

Vere dipendenze tra i task, o posta in gioco più alta: rivedere il piano proposto prima che inizi qualsiasi lavoro sul prodotto, promuoverlo a Full se l’obiettivo si rivela averne bisogno, poi eseguire e riprendere tra le sessioni secondo necessità.

Terminale — comandi slash

# Long-horizon work with real stakes: review before anything runs.
/dwp-create migrate the billing service to the new payments API
# ...review the proposed plan, then:
/dwp-execute
# ...interrupted? pick up again, even in a fresh session:
/dwp-resume

L’output di ogni piano — manifest, log di avanzamento, record dei task, evidenze dei gate — vive in una directory .dwp/ esclusa da git, nel repository stesso. Nulla viene inviato a o memorizzato da deepworkplan.com; la skill non effettua alcuna chiamata di rete.

Endpoint

Gli endpoint principali dell’API per agenti. La specifica completa e tipizzata — ogni operazione, parametro e schema di risposta — si trova nel documento OpenAPI.

Endpoint
`GET`	`/openapi.json`	Specifica OpenAPI 3.1 dell’intera API per agenti.
`GET`	`/llms.txt`	Indice curato di indicazioni per LLM — il punto d’ingresso consigliato per gli agenti.
`GET`	`/init.md`	Il prompt canonico di adozione di DWP (rende AI-first qualsiasi repository).
`GET`	`/{page}.md`	Qualsiasi pagina come Markdown sorgente nativo — in tutte le 17 lingue (ad es. /es/developers.md).
`GET`	`/api/health.json`	Indicatore di salute statico con collegamenti alla specifica e a questo portale.
`GET`	`/api/v1/index.json`	Catalogo versionato della famiglia v1: percorsi degli endpoint, versione del sito e collegamenti alla specifica.
`GET`	`/api/v1/sections.json`	La mappa del sito come JSON tipizzato — nome, percorso e descrizione per sezione.
`GET`	`/api/v1/pages.json`	Tutti gli endpoint Markdown in ogni lingua, raggruppati per codice lingua.
`GET`	`/api/v1/health.json`	Indicatore di stato versionato — il mirror v1 di /api/health.json.
`POST`	`/api/mcp`	Server MCP (Streamable HTTP, senza stato): initialize, ping, tools/list, tools/call.
`GET`	`/.well-known/ai-catalog.json`	Manifest di capacità ARD — l’agentmap dichiarato nel robots.txt.

I percorsi /api/* sconosciuti restituiscono un errore JSON strutturato con un suggerimento di risoluzione, mai una pagina di errore HTML.

Versionamento e deprecazione

La famiglia JSON versionata vive sotto /api/v1/ — index, sections, pages e health — e i percorsi canonici senza versione (/llms.txt, /{page}.md, /api/mcp) appartengono allo stesso contratto v1. Le modifiche che rompono la compatibilità arrivano solo in una nuova famiglia /api/v{N+1}/, mai dentro v1. Quando un endpoint viene deprecato, le sue risposte contengono Deprecation: true e una data Sunset almeno 180 giorni prima della rimozione, e un header Link punta al successore.

Limiti di richieste

Le risposte su /api/* contengono header di limite RFC 9331 — RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset e RateLimit-Policy — così gli agenti possono autoregolarsi in tempo reale; una risposta 429 aggiunge Retry-After. L’applicazione è best-effort al bordo (120 richieste ogni 60 secondi per visitatore) e l’accesso resta anonimo: senza chiavi, senza registrazione, senza livelli.

Server MCP

Un server Model Context Protocol senza stato su Streamable HTTP. Tre strumenti in sola lettura: get_init_prompt, list_site_sections e read_page. Sono supportate le versioni di protocollo 2025-03-26 e 2025-06-18; non è richiesta alcuna sessione.

Terminale — JSON-RPC su HTTP

# 1. Initialize (no session needed — the server is stateless)
curl -s https://deepworkplan.com/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1.0"}}}'

# 2. Discover the tools
curl -s https://deepworkplan.com/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Call one — read any page as source Markdown
curl -s https://deepworkplan.com/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"read_page","arguments":{"path":"/init"}}}'

Il manifest MCP si trova in /.well-known/mcp.json e la scheda del server in /.well-known/mcp/server-card.json. Claude, ChatGPT e qualsiasi client MCP possono chiamare questi strumenti in modo nativo.

Markdown per gli agenti

Ogni pagina renderizzata è pubblicata come Markdown sorgente nativo — non una conversione da HTML. Richieda il Markdown esplicitamente con un suffisso di URL o tramite negoziazione del contenuto HTTP su qualsiasi pagina.

Terminale — negoziazione del contenuto

# Ask for Markdown on any URL (content negotiation)
curl -s https://deepworkplan.com/methodology \
  -H 'Accept: text/markdown'

# Or fetch the .md mirror directly — every page has one, in every language
curl -s https://deepworkplan.com/es/developers.md

La negoziazione del contenuto restituisce lo stesso Markdown sorgente da cui il sito genera le pagine, nella lingua dell’URL richiesto.

Installare il kit

Il percorso di installazione ufficiale della skill Deep Work Plan — lo stesso comando che l’endpoint /init dà agli agenti. Funziona con qualsiasi agente di coding compatibile con le skills (Claude Code, Cursor, Codex, Gemini e altri).

Terminale — CLI per le skill e CLI ufficiale

# 1. Install the DWP skill — same command the /init endpoint gives agents
npx skills add DailybotHQ/deepworkplan-skill@latest

# 2. Official CLI — zero-dependency client over this API (Node >= 18),
#    prepared in the site repo's cli/ directory pending npm publication
deepworkplan init
deepworkplan read /es/developers

La skill viene vendorizzata in .agents/skills/deepworkplan/ dentro il Suo repository, così ogni agente che tocca il repository condivide la stessa metodologia. La CLI ufficiale deepworkplan — un client senza dipendenze sulla stessa API (init, sections, read, open, mcp) — è pronta per npm e vive nella directory cli/ del repository del sito fino alla pubblicazione.

Risorse leggibili dalle macchine

Punti un agente qui

Il percorso più rapido resta una riga: dia il prompt /init a qualsiasi agente di coding e quello installa la skill, fa l’onboarding del Suo repository e inizia a completare deep work.

Apri il prompt /init Leggi la metodologia