Writing briefs

Open a plan item and choose Research brief. The brief is the paid output: a complete Markdown file your own agent can write from, without Kitecraft repository access or a founder explanation. A title plus outline is not a brief; neither is a dump of scraped pages.

What you get

• Working title, slug, create or update action with the target URL for updates.
• Intended reader, search intent, reader promise, and business purpose.
• A distinct angle and what existing content it must complement or avoid repeating.
• Supported product facts, voice guidance with examples, and limitations.
• An outline with section purpose, questions, and supporting evidence.
• Research findings with source references and explicit unresolved claims.
• For updates: what to preserve, what to change, and why.
• Internal links, a call to action tied to a real capability, metadata suggestions, and direct writer instructions.

Every brief carries its revision, creation time, plan revision, content fingerprint, and evidence dates. Sources are quoted evidence with retrieval dates, never instructions. Missing evidence becomes a narrower claim or an explicit instruction, never an invented fact.

Request, poll, read

Research runs in the background. The request returns a durable operation ID immediately; leaving and returning resumes the same operation.

API:

• request: POST /api/v1/briefs/:id/request with {"itemId":"..."}
• status: GET /api/v1/briefs/:id/operations/:operationId
• read: GET /api/v1/briefs/:id/items/:itemId
• cancel: POST /api/v1/briefs/:id/operations/:operationId/cancel

CLI:

kitecraft brief request --id PROJECT_ID --json '{"itemId":"ITEM_ID"}'
kitecraft brief status --id PROJECT_ID --operation OPERATION_ID
kitecraft brief read --id PROJECT_ID --item ITEM_ID --format markdown > brief.md
kitecraft brief cancel --id PROJECT_ID --operation OPERATION_ID

MCP: brief_request, brief_status, brief_read, brief_cancel.

Poll status until ready, failed, or canceled. The read returns identical complete Markdown bytes plus a hash through every interface; the dashboard offers copy and an authenticated Markdown download. A preview may shorten long briefs and says so; the download always holds the complete artifact.

Free versus paid

Requesting and refreshing consume one researched brief from the account period allowance: seven per trial, 30 per paid billing period. Status reads, artifact reads, copy, download, cancellation, and plan date edits are free. A repeat request for current content returns the saved artifact without new spend; an explicit refresh is a new paid request while the previous brief stays readable. A failed operation for unchanged content resumes under its existing reservation when requested again, redelivered through a distinct recovery dispatch without a second charge. Interrupted research never repurchases an ambiguous attempt: completed evidence replays, pending outcomes stay pending with an honest limitation, and an ambiguous model output fails explicitly instead of rebuying the call. A failed refresh keeps the previous complete brief. When the plan item changes, the saved brief is marked stale instead of silently replaced.

Errors use the same shape everywhere: unknown items and missing targets return 400 with a specific next action, allowance exhaustion returns 402, conflicts return 409, and missing configuration returns 503. Revoked keys return 401, read-only keys return 403 on writes, and other accounts return 404.

Optional author material and writing references

Kitecraft researches the article. Your agent writes it. You can improve the writing packet with a perspective or a writing example without completing a questionnaire.

In Business and voice, choose brand-led or author-led as your default. Both aim for useful, readable articles. Brand-led writing uses the brand as narrator and can attribute genuine founder or team experience. Author-led writing can use that author's first person when you supply the experience.

In Content plan → Edit article → Optional author notes and references, paste notes or a voice-note transcript. Add a few selected reference passages, why you like each, what technique to learn, and light, moderate or strong influence. A reference is a writing aid, not automatically verified factual evidence. Your agent keeps its own wording and argument.

Save the item before requesting its brief. The material is frozen into that brief's packet. Changing it later does not alter an already created packet; request a fresh brief for the new inputs. Raw notes and reference excerpts are excluded from Kitecraft's hosted research prompts. The customer is responsible for the permissions of their own writer and for only adding material they may share.

The editorial skill 1.0.10 first explains the proposed article, its reader, the problem it will help solve and why your contribution would help. It then offers a short optional interview tailored to your relevant experience or perspective. Bullets or an audio transcript are enough. It also works without personal material. The default remains one draft and one integrated edit.

API and MCP use the same optional editorial field on PlanItemInput, with authorship, authorNotes and references. Omit it to preserve saved material; send null to clear it. The CLI's existing item payload accepts the same contract. Retrieve the complete packet with the usual brief operations, rather than copying only the outline.

Agent edits use the same operation

Read the plan to obtain its current revision and item ID. Then use plan_item or kitecraft plan item --id PROJECT_ID --json ... with this payload:

{
  "expectedRevision": 3,
  "itemId": "ITEM_ID",
  "editorial": {
    "authorship": "brand",
    "authorNotes": "",
    "references": [
      {
        "title": "A walkthrough worth learning from",
        "url": "https://example.com/walkthrough",
        "excerpt": "Paste a short selected passage you can share.",
        "why": "Keep one worked example through the decision.",
        "emulate": ["structure", "explanation"],
        "influence": "moderate"
      }
    ]
  }
}

For MCP, also supply id: PROJECT_ID. HTTP uses POST /api/v1/plans/PROJECT_ID/item with the payload above. Edits make no provider calls. Request research separately, then retrieve the full Markdown packet with brief_read or kitecraft brief read --id PROJECT_ID --item ITEM_ID --format markdown. Read the instructions and versioned skill embedded in that packet. Their text is the frozen version, even after the latest downloadable skill changes.

Let your agent choose the article

New packets include a frozen article-direction preparation instruction. Give your agent the business goals, reader opportunity, genuine author material and complete archive. Ask it to investigate what is worth saying, why that helps the reader and business, and how it would approach the article before it drafts. The result is a working editorial memo, open to revision as it learns. This can happen within your existing agent session.

If your host exposes archive tools, let the agent inspect source passages and optionally consult the earlier title, answer and outline. With authorized search/page tools it can pursue further questions. Keep the working direction alongside the original material for both the writer and editor. A plan is useful guidance; it does not turn generated ideas into facts or require the editor to preserve a weak structure.

Retrieve the complete packet, then treat it as a reference archive. Your agent starts with the reader, your contribution and explicit writing preferences, chooses the useful angle, and reads relevant original sources as needed. The researched title, question and outline are proposals. Website copy can inform terminology without becoming the article's structure or forcing a sales pitch.

An agent with file-reading tools can save the packet and inspect selected material. An agent without those tools needs the relevant original excerpts in its context. Reading a saved excerpt is not fresh research or independent verification. The editor makes one integrated revision, beginning with the article's usefulness and argument, then checking claims and sentences. No extra planning call or mandatory interview is required.

Choose the reader job before the outline

Tell your agent any explicit reader question or required update scope. Kitecraft's generated angle, answer and outline are proposals. The writer should decide what the reader needs, what the available material usefully answers and which structure delivers it. Author notes can be the central contribution, a supporting example, a separate article idea or irrelevant to this assignment. Good explanatory articles do not require a story. Ask the agent to note the chosen question and any material angle change beside the article, then write once and make one integrated edit.

Purpose and editorial control

Current packets open with the saved business context, audience and full goals, followed by genuine author material and resolved instructions. The reader question, article title, outline and researcher's suggested approach remain proposals in the archive. Observed website style is reference material; explicit customer preferences remain instructions. A business goal does not require a product pitch.

Your writer chooses the article's useful promise. Your editor can cut, rewrite, move and combine whole sections, including changing a weak angle within your task. Prefer a tighter article that delivers its promise to a long source inventory. There is no word quota or required founder story. Saved packets retain the instructions they were created with.

Choose how to write

New packets include three optional, versioned writing approaches in Complete resolved writing instructions:

• Discover: find the strongest useful contribution before committing to an outline.
• Decision: explain a worthwhile choice, its alternatives and consequences. Genuine experience can help, but a founder story is optional.
• Worked: teach through a concrete reader situation or comparison.

Your agent investigates the task, business goals, voice, sources and optional notes, then chooses an approach, the unchanged default, or another form that fits better. These techniques are examples, not the complete menu of possible articles. If using a listed technique, apply its draft fragment after the saved draft instructions and its edit fragment after the saved editor instructions. One draft, one integrated edit, the same output. The editor may change the approach when that makes a better article within your explicit task. Report the change in the existing edit notes.

These are experimental editorial options, not ranking promises. Existing saved packets stay frozen; a free read does not rewrite their instructions. New researched packets include the menu. Kitecraft prepares the research and writing handoff; your agent writes and publishes. No hosted writer or additional judge round is required.

Use the writing workflow

Newly compiled packets include the Kitecraft writing skill 1.0.1 and a Working input for both writer and editor section. Give your writer that original material and the frozen evidence/draft instructions. Keep the complete source archive available so your agent can consult relevant passages by source ID. The structured export repeats material for software clients; it does not all belong in the active writer or editor context. The generated outline and research advice remain proposals.

Then initialize an independent editor with the same material and archive, the complete draft, and the packet's frozen editorial skill/edit instructions. The editor implements the rewrite and returns the full article in the supplied output schema. No rating or judge loop is part of this recipe. Optional interview questions first explain the article, reader and purpose. No personal story is required.

Older saved packets keep their original frozen recipe. Retrieve the entire Markdown through the existing UI, API, CLI or MCP operation. Kitecraft's launch product prepares the packet; your agent writes and publishes.

Interview recordings and transcripts

See Interviews and transcripts for private recording uploads, full transcripts, correction and retry commands. MCP tool descriptions include accepted formats and the CLI/API upload path. brief_read returns current ready materials beside the frozen packet; Markdown-only exports need a separate material_list read.