-
Notifications
You must be signed in to change notification settings - Fork 0
Leak-audit site, campaign spec, and brief-request wiring #8
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
e65e282
053358a
4ae03bd
a2e87a8
6bd2bef
0574ed7
963d76b
f2956e9
f66187a
3a7cbc0
05ed124
d37d0cf
94a5f06
c7d6417
d22eaee
a1781f1
000eef6
c086a83
3274e94
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,127 @@ | ||
| --- | ||
| title: feat: Pipeline Loop Agent Desk | ||
| type: feat | ||
| date: 2026-06-18 | ||
| execution: code | ||
| --- | ||
|
|
||
| # feat: Pipeline Loop Agent Desk | ||
|
|
||
| ## Summary | ||
|
|
||
| Expand the TinyStudio Agent Desk from a single Pipeline Brief generator into a three-artifact applied-AI workflow: Pipeline Brief, Implementation Checklist, and Weekly Fix Report. The app remains self-serve, server-side AI powered, claim-safe, and approval-gated for external account or spend actions. | ||
|
|
||
| --- | ||
|
|
||
| ## Problem Frame | ||
|
|
||
| The current Agent Desk proves TinyStudio can collect high-ticket pipeline context and generate a useful first brief. The next product layer should bridge AI output into operational work: what to build first, what to track weekly, and what to fix next without positioning TinyStudio as an autonomous ad agency. | ||
|
|
||
| --- | ||
|
|
||
| ## Requirements | ||
|
|
||
| **Agent workflow** | ||
|
|
||
| - R1. The Agent Desk must generate three distinct artifacts from one intake: Pipeline Brief, Implementation Checklist, and Weekly Fix Report. | ||
| - R2. The Weekly Fix Report must use optional current-week metrics when supplied and must fall back to a tracker template when metrics are absent. | ||
| - R3. The Implementation Checklist must convert the diagnosis into approval-gated setup work across offer, funnel, creative, qualification, follow-up, CRM, tracking, and decision cadence. | ||
|
|
||
| **Public UI** | ||
|
|
||
| - R4. The public page must expose the three-artifact workflow as the first-class self-serve experience. | ||
| - R5. The intake must collect optional weekly lead-to-call metrics without making them required and without implying guaranteed performance targets. | ||
| - R6. The output panel must let users inspect and copy each artifact separately while preserving a useful all-in-one response for fallback. | ||
|
|
||
| **Safety and data boundary** | ||
|
|
||
| - R7. The Worker must keep AI generation server-side through Cloudflare Workers AI and must not store submitted business briefs or generated artifacts. | ||
| - R8. Public copy and generated output must avoid revenue, ROAS, booked-call, ranking, AI-visibility, conversion-lift, sales-lift, profit, or autonomous ad-buying guarantees. | ||
| - R9. Ad spend changes, campaign publishing, platform connections, CRM outcome syncing, claims, and compliance-sensitive work must remain approval-gated. | ||
|
|
||
| **Verification** | ||
|
|
||
| - R10. Static content checks must validate the new artifacts, section contract, safety language, and Cloudflare AI boundary. | ||
| - R11. A sample high-ticket scenario must exercise the end-to-end agent response and prove the outputs are useful without manual explanation. | ||
|
|
||
| --- | ||
|
|
||
| ## Key Technical Decisions | ||
|
|
||
| - **Single API response with structured sections:** The Worker should ask the model for exact top-level headings, split the markdown into named sections, and return both `sections` and a backward-compatible combined `brief`. This keeps the client simple while preserving compatibility with the existing one-output contract. | ||
| - **Optional metrics as prompt context only:** Weekly numbers belong in the request prompt and browser UI, not in D1. Existing D1 usage logging should remain lightweight and should not capture the business brief, the weekly metrics, or generated artifacts. | ||
| - **Client-side tabs over multiple API calls:** One agent run should produce all three artifacts. Tabs only change presentation, which keeps AI cost, rate limits, and consistency predictable. | ||
| - **Safety filter on combined generated text:** Existing forbidden-claim detection should run against the full generated response before any section is returned, so unsafe content cannot leak through a secondary tab. | ||
|
|
||
| --- | ||
|
|
||
| ## Implementation Units | ||
|
|
||
| ### U1. Worker section contract | ||
|
|
||
| - **Goal:** Generate and return Pipeline Brief, Implementation Checklist, and Weekly Fix Report as structured sections. | ||
| - **Requirements:** R1, R2, R3, R7, R8, R9 | ||
| - **Dependencies:** None | ||
| - **Files:** `src/worker.js`, `scripts/check-site.mjs` | ||
| - **Approach:** Extend the agent input with optional weekly metrics, update the prompt to require exact headings, add a section splitter, validate that all three sections are present, and keep the combined `brief` response for compatibility. | ||
| - **Patterns to follow:** Existing `/api/agent-audit` validation, retry, safety-filter, and no-brief-storage behavior in `src/worker.js`. | ||
| - **Test scenarios:** Submit a valid request with weekly metrics and expect all three response sections; submit a valid request without metrics and expect the Weekly Fix Report to become a tracker template; confirm unsafe generated claims are still rejected. | ||
| - **Verification:** Static checks cover the section splitter, prompt headings, metrics fields, and forbidden claims. | ||
|
|
||
| ### U2. Public workflow UI | ||
|
|
||
| - **Goal:** Make the page read as a self-serve workflow desk rather than a single brief generator. | ||
| - **Requirements:** R4, R5, R6, R8, R9 | ||
| - **Dependencies:** U1 | ||
| - **Files:** `public/index.html`, `public/script.js`, `public/styles.css`, `scripts/check-site.mjs` | ||
| - **Approach:** Add an optional weekly metrics group to the intake, render three output tabs backed by the structured API response, keep copy buttons scoped to the active artifact, and preserve a clear empty/error state. | ||
| - **Patterns to follow:** Existing Agent Desk layout, form submission, progressive enhancement, and status handling in `public/index.html`, `public/script.js`, and `public/styles.css`. | ||
| - **Test scenarios:** Load the page at desktop and mobile sizes; generate from sample context; switch tabs; copy the active artifact; verify empty, loading, success, and error states do not overlap or require technical explanation. | ||
| - **Verification:** Browser inspection plus static checks confirm artifact labels, metric fields, output tabs, and safety copy. | ||
|
|
||
| ### U3. Public truth and repo docs | ||
|
|
||
| - **Goal:** Keep machine-readable and maintainer-facing truth aligned with the new three-artifact workflow. | ||
| - **Requirements:** R4, R8, R9, R10 | ||
| - **Dependencies:** U1, U2 | ||
| - **Files:** `public/llms.txt`, `public/offer.md`, `README.md`, `MEMORY.md`, `specs/001-public-buyer-page/plan.md`, `specs/001-public-buyer-page/spec.md`, `specs/001-public-buyer-page/tasks.md` | ||
| - **Approach:** Update public docs to say the Agent Desk generates a Pipeline Brief, Implementation Checklist, and Weekly Fix Report. Preserve the no-guarantee and approval-gated boundaries. | ||
| - **Patterns to follow:** Existing public truth files use short, direct claim-safe wording. | ||
| - **Test scenarios:** Static content checks should fail if the new sections or safety boundaries are missing. | ||
| - **Verification:** `npm test` validates content, safety claims, and AI boundary checks. | ||
|
|
||
| ### U4. End-to-end verification and review | ||
|
|
||
| - **Goal:** Prove the implementation works locally before any ship path. | ||
| - **Requirements:** R10, R11 | ||
| - **Dependencies:** U1, U2, U3 | ||
| - **Files:** `scripts/check-site.mjs` | ||
| - **Approach:** Run the normal test command, run syntax checks where useful, browser-check desktop and mobile, and exercise `/api/agent-audit` with a sample high-ticket scenario. | ||
| - **Patterns to follow:** Existing project verification in `README.md`, `MEMORY.md`, and `specs/001-public-buyer-page/plan.md`. | ||
| - **Test scenarios:** Static test pass; sample AI response has all three artifacts; no forbidden claims; rendered page is nonblank and usable. | ||
| - **Verification:** Final report lists exact checks run and any unverified items. | ||
|
|
||
| --- | ||
|
|
||
| ## Scope Boundaries | ||
|
|
||
| - No payment collection, account provisioning, or paid subscription logic. | ||
| - No Meta, Google, CRM, WhatsApp, SMS, or email platform write automation. | ||
| - No campaign publishing, ad spend changes, CRM outcome syncing, or lead-message sending. | ||
| - No storage of submitted business briefs, weekly metrics, or generated artifacts. | ||
| - No public guarantees for revenue, ROAS, booked calls, profit, rankings, AI visibility, conversion lift, or sales lift. | ||
|
|
||
| --- | ||
|
|
||
| ## Risks & Dependencies | ||
|
|
||
| - **Model shape drift:** The model may ignore exact headings. Mitigation: parse sections defensively, retry through existing fallback models, and fail safely if required artifacts are missing. | ||
| - **Overclaiming by generation:** The model may produce unsafe claims. Mitigation: run the existing safety detector on the full response before returning it. | ||
| - **Metric interpretation risk:** Weekly metrics can be incomplete or noisy. Mitigation: ask the model to diagnose bottlenecks and next checks, not guarantee outcomes. | ||
| - **AI availability:** The feature depends on Cloudflare Workers AI binding. Mitigation: keep the existing safe unavailable state. | ||
|
|
||
| --- | ||
|
|
||
| ## Documentation / Operational Notes | ||
|
|
||
| No D1 migration is planned because the new inputs and outputs are not stored. Any deploy path must still run the review gate and existing `npm test` before publishing. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| --- | ||
| title: fix: Minimal-input Agent Desk | ||
| type: fix | ||
| date: 2026-06-18 | ||
| execution: code | ||
| --- | ||
|
|
||
| # fix: Minimal-input Agent Desk | ||
|
|
||
| ## Summary | ||
|
|
||
| Make the Pipeline Loop Agent Desk feel agent-native: customers provide a small business seed, and the agents infer the offer, buyer, funnel, hooks, follow-up, CRM, tracking, and weekly fix loop unless a real blocker remains. | ||
|
|
||
| --- | ||
|
|
||
| ## Problem Frame | ||
|
|
||
| The current page looks and behaves like an agency intake form. That makes paying customers do diagnosis work the agents should handle, and it weakens the promise that TinyStudio is self-serve with AI doing the heavy lifting. | ||
|
|
||
| --- | ||
|
|
||
| ## Requirements | ||
|
|
||
| - R1. The public form must require only email and a compact business snapshot. | ||
| - R2. Optional fields must stay available for better output, but they must not dominate the first screen. | ||
| - R3. The Worker must accept minimal input and prompt the model to infer missing pieces, mark assumptions, and ask only true blocker questions. | ||
| - R4. The generated artifacts must stay claim-safe and approval-gated for spend, publishing, platform connections, and compliance-sensitive actions. | ||
| - R5. Existing structured section, metric snapshot, storage, and safety tests must keep passing. | ||
|
|
||
| --- | ||
|
|
||
| ## Key Technical Decisions | ||
|
|
||
| - **Keep one endpoint:** `/api/agent-audit` remains the only agent run endpoint so rate limits, storage boundaries, and safety filtering stay centralized. | ||
| - **Use business snapshot as the seed:** The existing `business` field becomes the one required context field, avoiding a data migration or extra API contract. | ||
| - **Progressive disclosure:** Offer, audience, proof, follow-up, metrics, and funnel controls move behind an optional detail section rather than being removed. | ||
| - **Prompt over workflow code:** Missing-input behavior belongs in the system/user prompt so the agents use judgment instead of hard-coded questionnaire logic. | ||
|
|
||
| --- | ||
|
|
||
| ## Implementation Units | ||
|
|
||
| ### U1. Minimal-input validation | ||
|
|
||
| - **Goal:** Let customers run the agents with only email and business snapshot. | ||
| - **Requirements:** R1, R3, R5 | ||
| - **Dependencies:** None | ||
| - **Files:** `src/worker.js`, `public/script.js`, `scripts/test-agent-worker.mjs`, `scripts/test-agent-ui.mjs` | ||
| - **Approach:** Relax validation to require only `email` and `business`; update client-side messages and tests to prove offer/audience are optional. | ||
| - **Patterns to follow:** Existing `validateAgentInput`, `ERROR_MESSAGES`, and mocked Worker/UI tests. | ||
| - **Test scenarios:** Minimal body succeeds; missing business seed fails; UI submits without offer/audience. | ||
| - **Verification:** `npm test`. | ||
|
|
||
| ### U2. Agent-heavy prompt behavior | ||
|
|
||
| - **Goal:** Make the agent infer missing offer, buyer, funnel, creative, follow-up, CRM, and metrics assumptions before asking questions. | ||
| - **Requirements:** R3, R4, R5 | ||
| - **Dependencies:** U1 | ||
| - **Files:** `src/worker.js`, `scripts/test-agent-worker.mjs` | ||
| - **Approach:** Add prompt guidance for assumption-making, blocker-only questions, and customer-delight output. Keep the existing no-guarantee and approval-gated constraints. | ||
| - **Patterns to follow:** Current `agentSystemPrompt`, `agentUserPrompt`, and unsafe-output scrubber. | ||
| - **Test scenarios:** Minimal prompt includes inference guidance and labels absent optional fields as missing context rather than invalid input. | ||
| - **Verification:** Worker tests and live API smoke. | ||
|
|
||
| ### U3. Progressive-disclosure intake UI | ||
|
|
||
| - **Goal:** Replace the visible questionnaire with a compact agent workspace. | ||
| - **Requirements:** R1, R2 | ||
| - **Dependencies:** U1 | ||
| - **Files:** `public/index.html`, `public/styles.css`, `scripts/check-site.mjs` | ||
| - **Approach:** Keep email, business snapshot, and constraints visible; move market, funnel, offer, audience, proof, follow-up, and weekly numbers into a collapsible optional section. | ||
| - **Patterns to follow:** Existing single-page Agent Desk layout and output tabs. | ||
| - **Test scenarios:** Desktop and mobile render without oversized form controls; optional details remain accessible. | ||
| - **Verification:** Browser check at `http://127.0.0.1:8788/`. | ||
|
|
||
| --- | ||
|
|
||
| ## Scope Boundaries | ||
|
|
||
| - No ad account, CRM, WhatsApp, SMS, email, or payment platform write automation in this fix. | ||
| - No storage of business snapshots, optional details, metrics, or generated artifacts. | ||
| - No public claims about guaranteed outcomes. | ||
| - No new paid onboarding, account provisioning, or subscription logic. | ||
|
|
||
| --- | ||
|
|
||
| ## Risks & Dependencies | ||
|
|
||
| - **Weak seed risk:** Some users will submit vague snapshots. Mitigation: prompt the agent to make explicit assumptions and ask only true blocker questions. | ||
| - **Over-inference risk:** The model may invent proof or outcomes. Mitigation: preserve the existing unsafe-output filter and no-invented-proof prompt rules. | ||
| - **Hidden detail risk:** Power users may miss optional fields. Mitigation: keep the optional drawer visible, short, and clearly labeled. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| -- The leak-audit form collects the site to be audited alongside the email. | ||
| -- Without the URL a brief request is not actionable — there is nothing to read. | ||
| -- Nullable so existing rows and the Agent Desk signup path stay valid. | ||
| ALTER TABLE email_signups ADD COLUMN website TEXT; |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,7 +7,9 @@ | |
| "scripts": { | ||
| "dev": "wrangler dev --remote --ip 127.0.0.1 --port 8788 --persist-to /tmp/tinystudio-agent-worker", | ||
| "check": "node scripts/check-site.mjs", | ||
| "test": "npm run check", | ||
| "test": "npm run check && npm run test:worker && npm run test:ui", | ||
| "test:worker": "node --test scripts/test-agent-worker.mjs", | ||
| "test:ui": "node --test scripts/test-agent-ui.mjs", | ||
| "leads:list": "wrangler d1 execute tinystudio_email_signups --remote --command \"SELECT email, source, page_path, created_at, updated_at FROM email_signups ORDER BY updated_at DESC LIMIT 100;\"", | ||
| "leads:export": "wrangler d1 execute tinystudio_email_signups --remote --command \"SELECT email, source, page_path, created_at, updated_at FROM email_signups ORDER BY updated_at DESC;\" --json", | ||
|
Comment on lines
13
to
14
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
After this PR, Useful? React with 👍 / 👎. |
||
| "migrate:remote": "wrangler d1 migrations apply tinystudio_email_signups --remote", | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Hyphenate the compound modifier.
"server-side AI powered" reads as two separate modifiers. Use "server-side AI-powered".
✏️ Proposed wording fix
📝 Committable suggestion
🧰 Tools
🪛 LanguageTool
[grammar] ~12-~12: Use a hyphen to join words.
Context: ...e app remains self-serve, server-side AI powered, claim-safe, and approval-gated ...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Source: Linters/SAST tools