diff --git a/.agents/skills/publish-shipping-log/SKILL.md b/.agents/skills/publish-shipping-log/SKILL.md new file mode 100644 index 0000000..a8d87bf --- /dev/null +++ b/.agents/skills/publish-shipping-log/SKILL.md @@ -0,0 +1,66 @@ +--- +name: publish-shipping-log +description: Create and package evidence-led OpenAPI Studio Shipping Log posts for LinkedIn or X, including numbered written entries, truthful metrics, and generated editorial hero images. Use when asked to publish, draft, continue, or package the build-in-public journey, shipping journal, founder log, progress update, or next Shipping Log entry. +--- + +# Publish Shipping Log + +Create one truthful, written field note and its social hero. Keep this skill repository-local. Never install or modify a global skill. + +## Workflow + +1. Read `AGENTS.md`, `.docs/shipping-log-series.md`, and `.docs/design-partner-operating-ledger.md` completely. +2. Inspect `git log`, the active pull request, CI state, and relevant shipped artifacts. Use them only as evidence. Do not change product code. +3. Select the next three-digit log number. Do not reuse a published number. +4. Draft the post using the established structure: + - log number + - ISO date + - current product stage and MRR + - what happened + - observation + - evidence + - next uncertainty + - `Log closed.` +5. Keep the post between 120 and 250 words. Write in first person. Use exact counts. Never imply traction, customers, revenue, or released functionality without evidence. +6. Save the post as `.docs/shipping-log-NNN-YYYY-MM-DD.md`. +7. Generate one LinkedIn landscape hero with the built-in `$imagegen` skill and `image_gen` tool. Do not use an API-key fallback unless the user explicitly requests it. +8. Copy the selected generated image into `.docs/shipping-log-NNN-linkedin-hero.png`. Preserve the original generated file. +9. Inspect the image with `view_image`. Verify all required text, hierarchy, crop safety, and visual quality. Make one targeted regeneration when a material defect exists. +10. Validate the post and asset, then report their paths. Commit, push, merge, deploy, or publish externally only when the user authorizes that action. + +## Editorial Contract + +- Lead with an operational fact, not an engagement hook. +- Separate observation from interpretation. +- Name failures without manufactured vulnerability. +- End with the next uncertainty, not a generic audience question. +- Never expose prospect identities or private conversation details. +- Never use em dashes in any content or image text. +- Use no more than four relevant hashtags. +- Do not mention Avatar in published output. + +## Hero Contract + +Use a premium archival field-note design: + +- LinkedIn landscape ratio near `1.91:1` +- warm uncoated paper and restrained halftone texture +- near-black ink with forest-green accent +- Swiss editorial grid and strong safe margins +- large `SHIPPING LOG NNN` identifier +- exact strings for project, date, stage, MRR, and `@milonspace` +- only metrics supported by the post + +Avoid movie references, neon sci-fi interfaces, gradients, glassmorphism, generic AI symbols, fake dashboards, decorative clutter, watermarks, and extra prose. + +## Validation + +Run the smallest checks that prove the package: + +```powershell +rg -n "—" .docs/shipping-log-NNN-YYYY-MM-DD.md +git diff --check +bun -e "import sharp from 'sharp'; const m=await sharp('.docs/shipping-log-NNN-linkedin-hero.png').metadata(); console.log(m.width, m.height, m.width/m.height)" +``` + +The em-dash scan must return no matches. Confirm the post word count is within range and the image ratio is between `1.89` and `1.93`. diff --git a/.agents/skills/publish-shipping-log/agents/openai.yaml b/.agents/skills/publish-shipping-log/agents/openai.yaml new file mode 100644 index 0000000..be4bd61 --- /dev/null +++ b/.agents/skills/publish-shipping-log/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: 'Publish Shipping Log' + short_description: 'Create evidence-led shipping posts and heroes' + default_prompt: 'Use $publish-shipping-log to draft and package the next OpenAPI Studio Shipping Log post.' diff --git a/.docs/2026-07-18-outreach-sprint-plan.md b/.docs/2026-07-18-outreach-sprint-plan.md new file mode 100644 index 0000000..f7e2fd8 --- /dev/null +++ b/.docs/2026-07-18-outreach-sprint-plan.md @@ -0,0 +1,21 @@ +# Design Partner Outreach Sprint + +## Objective + +Book five qualified workflow interviews in seven days. Validate whether small API teams repeatedly struggle to review breaking OpenAPI changes before shipping. Do not pitch a broad API platform. + +## Scope + +Create only sales assets, prospecting rules, outreach scripts, and aggregate tracking for X, Threads, Facebook, and LinkedIn. Keep prospect identities and conversation notes outside Git. Do not build product features, buy tools, automate messages, or publish from an agent account. + +## Execution + +1. Build a private list of 50 prospects using the criteria in `.docs/design-partner-outreach-playbook.md`. +2. Send 10 personalized messages per day for five days. +3. Follow up once after three days when there is no reply. +4. Run 15-minute discovery calls using the existing conversation prompts. +5. Update aggregate funnel counts daily. + +## Decision Gate + +Continue the problem direction only if the sprint produces at least five qualified replies, three conversations, and two prospects who confirm the problem is frequent and costly. Do not treat likes, impressions, or generic encouragement as demand evidence. diff --git a/.docs/design-partner-operating-ledger.md b/.docs/design-partner-operating-ledger.md index ac5fd06..b2d8706 100644 --- a/.docs/design-partner-operating-ledger.md +++ b/.docs/design-partner-operating-ledger.md @@ -20,6 +20,14 @@ A qualified prospect is part of a small software team that actively maintains an | ---- | ---------------: | ---------: | ----------------: | ------------: | --------------: | ---------------------: | ------------------ | -------------- | | TBD | 0 | 0 | 0 | 0 | 0 | 0 | None | Start outreach | +## Seven-Day Outreach Sprint + +| Date | Researched | Sent | Follow-ups | Qualified replies | Calls booked | Calls held | Repeated pain confirmed | +| ---------- | ---------: | ---: | ---------: | ----------------: | -----------: | ---------: | ----------------------: | +| 2026-07-18 | 10 | 0 | 0 | 0 | 0 | 0 | 0 | + +Update this table with aggregate counts only. The daily target is 10 researched messages. Stop after one follow-up per prospect. + ## Conversation Prompts - Walk me through the last OpenAPI change your team made. diff --git a/.docs/design-partner-outreach-playbook.md b/.docs/design-partner-outreach-playbook.md new file mode 100644 index 0000000..e6bb262 --- /dev/null +++ b/.docs/design-partner-outreach-playbook.md @@ -0,0 +1,49 @@ +# Design Partner Outreach Playbook + +## Prospect Filter + +Contact people only when all four signals are visible: + +1. They are a founder, engineering lead, platform engineer, or API owner at a 2 to 30 person software team. +2. Their product exposes or consumes an API. +3. Their public work mentions OpenAPI, Swagger, API docs, SDK generation, contract tests, or breaking changes. +4. They posted, shipped, or contributed within the last 90 days. + +Exclude recruiters, students, consultants without an active product, large-enterprise employees without buying influence, and teams seeking free hosting only. + +## Search Patterns + +- X and Threads: `"OpenAPI" breaking change`, `"Swagger" docs`, `"API contract" review` +- LinkedIn: posts containing OpenAPI or API documentation, filtered to founders and engineering leads at small companies +- Facebook: API development, SaaS founder, backend engineering, and developer tooling groups where promotion is allowed +- GitHub discovery: recent OpenAPI repository activity, then contact only through a public professional profile + +## First Message + +Personalize the first sentence with a real post, repository, or workflow detail. + +> Saw your work on [specific API or post]. When your OpenAPI contract changes, how does your team catch a breaking change before users find it? I am researching this workflow with small API teams. Could I ask you three questions in a 15-minute call? No sales deck. + +## Public Post + +> Small API teams: what happened the last time an OpenAPI change broke an SDK, integration, or API document? I am studying how teams review contract changes before release. If this is a recurring problem for you, I would value a 15-minute workflow walkthrough. + +## Follow-Up + +> One follow-up, then I will close the loop. I am specifically trying to learn whether reviewing OpenAPI changes is a real recurring problem or just an occasional annoyance. Is this relevant to your team? + +## Reply Handling + +- If interested: schedule 15 minutes and ask workflow questions before showing the page. +- If they ask what it is: say, "A focused OpenAPI change-review workflow for small teams. The current page is a demand test, not a finished editor." +- If price comes up: test `$29 per workspace per month after the pilot`. Ask what result would make that reasonable. +- If not relevant: ask which role owns the problem, then stop. +- If no reply after one follow-up: stop. + +## Daily Operating Limit + +Spend no more than 60 minutes on prospecting and 30 minutes on follow-ups. Send 10 researched messages, not mass outreach. Track qualified replies and calls. Ignore vanity metrics. + +## Private Prospect Record + +Store this outside Git: name, role, company, profile URL, qualification signal, channel, first contact date, follow-up date, reply state, call date, exact problem language, frequency, consequence, current workaround, buyer, and willingness to pay. diff --git a/.docs/openapi-ai-agent-teams-x-hero-generated.png b/.docs/openapi-ai-agent-teams-x-hero-generated.png new file mode 100644 index 0000000..b3a5f8e Binary files /dev/null and b/.docs/openapi-ai-agent-teams-x-hero-generated.png differ diff --git a/.docs/openapi-ai-agent-teams-x-hero.png b/.docs/openapi-ai-agent-teams-x-hero.png new file mode 100644 index 0000000..c13d1b4 Binary files /dev/null and b/.docs/openapi-ai-agent-teams-x-hero.png differ diff --git a/.docs/openapi-ai-agent-teams-x-hero.svg b/.docs/openapi-ai-agent-teams-x-hero.svg new file mode 100644 index 0000000..f3e1b8b --- /dev/null +++ b/.docs/openapi-ai-agent-teams-x-hero.svg @@ -0,0 +1,62 @@ + + + + + + + + + + + + + + + + + + + + + + + + OPENAPI / AGENT TEAMS / CONTRACT REVIEW + AI CODING AGENTS + MAKE OPENAPI DRIFT + MORE EXPENSIVE. + Three correct pull requests can still create one broken contract. + + + + + + + CONTRACT IMPACT + BREAKING CHANGE + + + GET /invoices/{id} + − dueDate + + paymentDueAt + + + + 2 CLIENTS AFFECTED + HUMAN DECISION REQUIRED + + + + + + + @milonspace + milon + + + + + + + + diff --git a/.docs/shipping-log-001-linkedin-hero.png b/.docs/shipping-log-001-linkedin-hero.png new file mode 100644 index 0000000..3cadbea Binary files /dev/null and b/.docs/shipping-log-001-linkedin-hero.png differ diff --git a/.docs/shipping-log-series.md b/.docs/shipping-log-series.md new file mode 100644 index 0000000..758bb07 --- /dev/null +++ b/.docs/shipping-log-series.md @@ -0,0 +1,86 @@ +# OpenAPI Studio Shipping Log + +## Purpose + +Publish the journey from zero revenue to a useful paid product as numbered LinkedIn field notes. Each entry records the current position, a direct observation, the evidence, and the next decision. + +The format borrows one useful idea from Avatar's logs: preserve what happened and how the operator's understanding changed over time. Do not copy its dialogue, fictional terminology, or visual identity. + +## Post Format + +```text +SHIPPING LOG 001 +Date: YYYY-MM-DD +Position: [stage], [$ MRR] + +[What happened] + +Observation: +[What changed in my understanding] + +Evidence: +[Counts, shipped artifact, or customer language] + +Next: +[The next uncertainty being tested] + +Log closed. +``` + +Keep entries between 120 and 250 words. Write in first person. Include one screenshot, artifact, or metric when it adds proof. Do not add a motivational lesson, manufactured drama, or a product pitch. + +## Shipping Log 001 + +**SHIPPING LOG 001** + +**Date: 2026-07-19** + +**Position: public preview, $0 MRR** + +I restarted OpenAPI Studio from a clean repository. + +The old product had more features, but no clear path to revenue. The rebuild initially repeated the same mistake in a different form. I treated a finished landing page as proof of progress. + +It was not. + +The first version looked generic, buried the main action below the fold, and tried to explain too much before establishing one urgent problem. + +**Observation:** + +Product surface is not evidence. A polished page is not evidence. The next feature is not automatically progress. + +I stopped feature work and narrowed the test to one pain: catching breaking OpenAPI changes before users do. + +**Evidence:** + +- Public preview shipped +- Repository made public and documented honestly +- One $29 pricing hypothesis +- Ten researched prospects +- Zero customers +- Zero revenue + +**Next:** + +Speak with five small API teams. If the same expensive workflow problem repeats, continue. If it does not, change the problem before changing the code. + +Log closed. + +#buildinpublic #OpenAPI #DeveloperTools #SaaS + +## Next Entries + +- `002`: Ten messages sent. What earned replies and what was ignored. +- `003`: First qualified conversation. The workflow, workaround, and consequence. +- `004`: Pricing resistance. Whether $29 is expensive or simply irrelevant. +- `005`: The first product slice approved by customer evidence. + +## Editorial Rules + +- Lead with the operational fact, not a hook engineered for engagement. +- Use exact counts. Never imply traction. +- Separate observation from interpretation. +- Name failures without performing vulnerability. +- Do not expose prospect identities or private conversation details. +- Do not present prototypes as released features. +- End with the next uncertainty, not a generic question. diff --git a/.docs/social-article-openapi-ai-agent-teams.md b/.docs/social-article-openapi-ai-agent-teams.md new file mode 100644 index 0000000..09c259c --- /dev/null +++ b/.docs/social-article-openapi-ai-agent-teams.md @@ -0,0 +1,125 @@ +# Social Article: OpenAPI and AI Coding Agent Teams + +## X Article + +### AI Coding Agents Make OpenAPI Drift More Expensive + +AI coding agents can implement several backend changes in parallel. That is useful until three correct pull requests produce one inconsistent API contract. + +The failure is rarely invalid YAML. It is semantic drift. + +One agent adds a required response field. Another changes an enum. A third updates an SDK or documentation page using yesterday's contract. Every change can pass its local tests while the combined release breaks a consumer. + +OpenAPI is not just documentation. The OpenAPI Specification defines a language-independent interface that humans and computers can use to understand an HTTP API without reading its source code. In an agent-assisted workflow, that document becomes shared coordination state. + +If agents treat it as a generated afterthought, development velocity increases while contract confidence falls. + +### Why agent teams expose the problem + +Human teams already create API drift. Agent teams change the economics: + +1. More changes happen concurrently. +2. Each agent sees only the context supplied to its task. +3. Generated SDKs, tests, docs, and server code can create competing sources of truth. +4. A syntactically valid contract can still describe the wrong behavior. +5. Reviewers receive more output without gaining more attention. + +The bottleneck moves from writing code to making reliable decisions about change. + +### The minimum contract gate + +A small team does not need a governance platform. It needs one disciplined merge boundary. + +**1. Name one source of truth** + +Choose the OpenAPI document or the implementation as authoritative. Do not let each agent decide. If the contract is generated, define exactly when and from what source. + +**2. Declare contract impact in every task** + +Each issue should state whether paths, parameters, request bodies, responses, schemas, security, or error behavior may change. “No API change” should be testable, not assumed. + +**3. Review the contract diff before generated output** + +Separate the human decision from SDK and documentation noise. Show removed operations, new required fields, type changes, enum changes, authentication changes, and response-code changes first. + +**4. Validate behavior, not only structure** + +Schema validation catches malformed descriptions. It does not prove that the running API, examples, and generated clients agree. Add focused conformance tests at the boundary. + +**5. Require a human decision for breaking changes** + +Agents can classify and explain impact. A person accountable for consumers should approve the change. Existing pull-request protections still matter when agents produce the pull requests. + +**6. Generate downstream artifacts after approval** + +Once the contract decision is accepted, regenerate SDKs and documentation from that exact revision. Record the contract hash or commit so every artifact has traceable provenance. + +### What good looks like + +The useful output is not “OpenAPI validation passed.” + +It is: + +> This pull request removes `dueDate`, adds required `paymentDueAt`, affects two generated clients, and needs a migration decision before merge. + +That gives the reviewer a decision, not another file to inspect. + +AI coding agents should reduce implementation work. They should not make API consumers discover contract decisions in production. + +I am speaking with small API teams about how they review OpenAPI changes today. If contract drift or breaking-change review is a recurring problem for your team, I would value a 15-minute workflow walkthrough. No sales deck. + +Sources: + +- OpenAPI Specification 3.2.0: https://spec.openapis.org/oas/latest.html +- OpenAPI best practices: https://learn.openapis.org/best-practices.html +- GitHub coding agent workflow and review controls: https://github.blog/news-insights/product-news/github-copilot-meet-the-new-coding-agent/ + +## LinkedIn Version + +### AI coding agents do not remove API coordination. They make it the bottleneck. + +Three agents can produce three correct pull requests and still create one inconsistent API contract. + +One adds a required response field. One changes an enum. Another updates an SDK from yesterday's OpenAPI document. Local tests pass. The consumer breaks. + +The problem is not usually invalid YAML. It is semantic drift. + +OpenAPI is a machine-readable interface for humans and tools. In an agent-assisted team, it should be treated as shared coordination state, not documentation generated at the end. + +A small team needs one contract gate: + +1. Define one source of truth. +2. State API impact in every task. +3. Review the contract diff before generated SDK and documentation noise. +4. Test whether the implementation, examples, and contract agree. +5. Require human approval for breaking changes. +6. Generate downstream artifacts from the approved contract revision. + +The review output should not be “validation passed.” It should say: + +> This change removes `dueDate`, adds required `paymentDueAt`, affects two clients, and needs a migration decision before merge. + +That is the real job: turn a large diff into a clear consumer-impact decision. + +AI agents increase implementation throughput. Without a contract review boundary, they also increase the speed and surface area of API drift. + +I am researching how small API teams review OpenAPI changes. If this is a recurring problem in your workflow, I would value a 15-minute walkthrough. No sales deck. + +#OpenAPI #APIDesign #DeveloperTools #AICoding #SoftwareEngineering + +## Short X Post + +AI coding agents can produce three correct pull requests and one inconsistent API contract. + +The failure is rarely invalid YAML. It is semantic drift across implementation, OpenAPI, SDKs, tests, and docs. + +The missing control is a contract-impact gate before merge. + +How does your team catch this today? + +## Publishing Notes + +- Publish the LinkedIn version first without a product link. Put the OpenAPI specification link in the first comment if reach is a concern. +- Publish the X Article within 24 hours. Use the short post as its lead-in. +- Reply to substantive answers with a workflow question. Do not pitch immediately. +- Measure qualified replies and conversations, not impressions.