[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-75450":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":8,"languages":8,"totalLinesOfCode":8,"stars":9,"forks":10,"watchers":11,"openIssues":12,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":12,"stars7d":12,"stars30d":14,"stars90d":13,"forks30d":13,"starsTrendScore":15,"compositeScore":16,"rankGlobal":8,"rankLanguage":8,"license":8,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":8,"pushedAt":8,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":13,"starSnapshotCount":13,"syncStatus":14,"lastSyncTime":24,"discoverSource":25},75450,"my-ai-workflow","maiobarbero\u002Fmy-ai-workflow","maiobarbero",null,118,10,116,1,0,2,3,3.12,false,"main",true,[],"2026-06-12 02:03:34","# My AI-Assisted Workflow\n\n> How I built a structured AI-assisted development workflow as a Tech Lead, where the real work happens before a single line of code is written.\n\n📖 **Full article:** [maiobarbero.dev\u002Farticles\u002Fai-assisted-workflow](https:\u002F\u002Fwww.maiobarbero.dev\u002Farticles\u002Fai-assisted-workflow?utm_source=github)\u003Cbr>\n📖 **TOE Framework article:** [https:\u002F\u002Fwww.maiobarbero.dev\u002Farticles\u002Fproject-complexity-ai-skills](https:\u002F\u002Fwww.maiobarbero.dev\u002Farticles\u002Fproject-complexity-ai-skills?utm_source=github)\n\n---\n\n## The Problem\n\nVanilla AI-assisted coding feels fast — open a chat, describe what you want, ship something that works. But the speed comes at a cost: features that nobody fully understands, edge cases nobody thought to handle, and architecture that doesn't survive the next feature.\n\nThis workflow is the answer to one question: **how do you get the speed benefits of AI assistance without losing the clarity and intentionality that makes software maintainable?**\n\nThe short answer: the real work happens *before* the coding starts.\n\n---\n\n## Core Principle\n\nAI is great at **implementation**. It's genuinely bad at figuring out what you actually want, catching implicit assumptions, and telling you when your mental model is wrong.\n\n**That's your job. It will always be your job.**\n\nEvery step in this workflow shares the same structure:\n\n> AI produces something → you review it with full context → it gets created.\n\nThe AI accelerates production. **The review is always yours.**\n\n---\n\n## The Workflow\n\n```\nFree-form Plan → PRD → Issues → Tasks → Code → Review → Final Audit\n```\n\n### Step 1 — Free-form Plan\nWrite a document in plain language. Describe the problem, your initial thinking, the constraints you're aware of, and the things you're uncertain about. No required structure. Nobody reads it but you. Its only job is to get the thinking out of your head.\n\n> The quality of everything downstream depends entirely on the quality of this step.\n\n### Step 2 — PRD (`write-a-prd`)\nThe free-form plan becomes the input to a structured interview. The skill explores the codebase, then interviews you about every aspect of the plan — walking down each branch of the design tree, resolving dependencies one by one.\n\nThe output is a structured **PRD** file containing:\n- Problem statement & solution description\n- Extensive user stories (the backbone of everything that follows)\n- Implementation decisions (modules, interfaces, schema changes, API contracts)\n- Module design & testing decisions\n- Explicit out-of-scope items\n\n### Step 3 — Issues (`prd-to-issues`)\nThe PRD becomes a set of issues using **vertical slices** — tracer bullets that cut through every integration layer end-to-end, never just a single layer.\n\nEach issue is classified as:\n- **AFK** — AI can implement and merge without human interaction\n- **HITL** — a human decision is required at some point\n\nEach issue contains: end-to-end behavior description, a \"how to verify\" section, acceptance criteria in Given\u002FWhen\u002FThen format (including error cases), blockers, and references to the user stories it addresses.\n\n### Step 4 — Tasks (`issues-to-tasks`)\nEach issue is broken down into concrete, ordered tasks — **one task per focused AI session**. If a task can't be completed in a single session, it's too large.\n\nTask descriptions are written as **instructions to the AI that will execute them**, not as notes to a human. They specify which files to touch, which existing patterns to follow, and what done looks like.\n\nOrder follows: Schema → Logic → API → UI, with tests interleaved throughout.\n\n### Step 5 — Handoff to Code\nEach task description is a self-contained prompt. Open a fresh session, paste the task description plus the parent issue for context, and implement.\n\n**Fresh context per task is intentional.** Long sessions drift — the model starts making decisions based on what it already did rather than what the task requires.\n\n### Step 6 — Code Review (`code-review`)\nEvery PR goes through a structured six-pass review before merge:\n\n1. Logic errors\n2. Operation ordering\n3. Bad practices\n4. Security\n5. Magic strings and values\n6. Pattern improvements\n\n> Pay particular attention to **operation ordering** — AI tends to do the right things in the wrong sequence (e.g. sending a notification before committing a transaction).\n\n### Step 7 — Final Audit (`final-audit`)\nA cross-cutting audit at the end of a feature, looking at things that can only be evaluated across the whole implementation: inconsistencies between modules, patterns replicated incorrectly, security assumptions that break down across the full surface area.\n\n---\n\n## What This Workflow Is Not\n\n- **Not fast to set up.** Planning and PRD steps take real time. It pays off only if you genuinely believe thinking time before coding is cheaper than debugging time after.\n- **Not a replacement for engineering judgment.** The AI will suggest reasonable things at every step that are wrong for your specific situation. Your review exists precisely because the AI lacks knowledge of your team's conventions, your users' actual behavior, and your codebase's hidden complexity.\n\n---\n\n## Project Complexity Skills\n\nThis repository includes two AI agent skills for diagnosing and managing project complexity.\n\n### `project-complexity-mapper`\n\nTurns a rough project idea, problem statement, or messy notes into a structured project complexity diagnosis.\n\nIt uses the TOE framework:\n\n- Technical complexity\n- Organizational complexity\n- External complexity\n\nOutputs include:\n\n- TOE findings by category\n- Severity based on TOE score + project impact\n- Overall project quadrant\n- Per-hotspot quadrant matrix\n- Mermaid complexity map\n- Management-fit recommendations\n- Human-readable handoff table\n\nDefault mode is a fast scan. A complete 47-element TOE assessment is available when requested.\n\n### `project-complexity-action-planner`\n\nRuns after `project-complexity-mapper`.\n\nIt consumes the complexity diagnosis and turns it into a practical intervention plan.\n\nOutputs include:\n\n- Intervention backlog\n- Sequencing\n- Suggested owner roles\n- Decision gates\n- Reassessment triggers\n- Risks in the plan\n- Execution handoff\n\nThis skill does not redo the TOE diagnosis. It uses the mapper output as input and focuses on turning complexity insight into management action.\n\n---\n\n## Credits\n\nThis workflow was adapted from Mark Pocock's [skills](https:\u002F\u002Fgithub.com\u002Fmattpocock\u002Fskills\u002Ftree\u002Fmain).\nProject Management skills use TOE Framework from TU Delft\n\n---\n\n## Author\n\n**Matteo \"Maio\" Barbero** — Software Engineer & Tech Lead\n\n- 🌐 [maiobarbero.dev](https:\u002F\u002Fwww.maiobarbero.dev\u002F)\n\n\n*Tags: #AI #Workflow #TechLeadership #Productivity*\n","该项目旨在构建一个结构化的AI辅助开发工作流，适用于技术领导者在编写代码前进行详尽规划。其核心功能包括从自由形式的计划到产品需求文档（PRD）转换、自动生成问题列表以及任务分配等步骤，利用AI加速实现过程的同时保持对项目整体架构与细节的高度控制。通过明确分工——AI负责快速生成内容，而人类则专注于审查与决策——确保了软件项目的可维护性和清晰度。适合于需要高质量、复杂软件系统开发且希望充分利用AI提高效率但不牺牲最终产品质量的场景。","2026-06-11 03:52:49","CREATED_QUERY"]