# SpecStory > AI development workflow platform that preserves the intent behind code generation, keeping prompts and specifications together with generated code. SpecStory enhances AI-powered software development by making AI output understandable and maintainable. We believe "Intent is the new source code" - in AI-first development, understanding the "why" behind code is as important as the code itself. ## Products - [SpecStory Extensions](https://specstory.com): Free extensions for Cursor, VS Code with GitHub Copilot, and Claude Code that auto-save prompts alongside generated code - [BearClaude](https://bearclaude.specstory.com): Standalone macOS app for spec-first development with Claude ## Resources - [Documentation](https://docs.specstory.com): Getting started guides and API references - [Blog](https://specstory.com/blog): Articles about AI development best practices - [Whitepaper](https://specstory.com/whitepapers/beyond-code-centric-specstory-2025.pdf): "Beyond Code-Centric" - How AI shifts the bottleneck from coding to specification clarity - [GitHub](https://github.com/specstoryai): Open source projects and examples ## Company - [About](https://specstory.com/company): Our mission and team - [For Teams](https://specstory.com/teams): Git integration for prompt-aware code reviews - [Privacy Policy](https://specstory.com/privacy): How we protect your data - [Terms of Service](https://specstory.com/terms): Legal terms for using SpecStory ## All Pages - [Homepage](https://specstory.com/): The main landing page for SpecStory. Features the hero section with "Intent is the new source code" messaging, product demonstrations for SpecStory Extensions and BearClaude, trusted company logos (NVIDIA, Alibaba, Uber, Affirm, Instacart, Crypto.com, Chewy, GoDaddy, Automattic, ThoughtWorks, MIT, SAP), and two development pathways: enhancing current workflow or embracing spec-first development. - [For Teams](https://specstory.com/teams): SpecStory for development teams. Features Git integration for prompt-aware code reviews, shared AI development practices, team collaboration features, and early access program. Explains how teams can maintain context across AI-assisted development, share prompts and specifications, and build collective intelligence. - [Company](https://specstory.com/company): About SpecStory, our mission to make AI development more intentional and understandable. Information about the founding team, company values, contact information, and career opportunities. We believe AI changes everything about how we build software. - [Privacy Policy](https://specstory.com/privacy): Our commitment to user privacy and data protection. Details about data collection, usage, storage, and user rights. SpecStory follows privacy-first principles with local storage by default and optional cloud sync. We do not sell user data and maintain strict data protection standards. - [Terms of Service](https://specstory.com/terms): Legal terms and conditions for using SpecStory services. Covers user agreements, acceptable use policies, intellectual property rights, disclaimers, and limitations of liability. By using SpecStory, users agree to these terms. - [Editor Tracker](https://specstory.com/editor-tracker): Tool for tracking and analyzing AI-assisted code generation metrics. Helps developers understand their AI usage patterns, measure productivity gains, and optimize their AI-powered development workflow. Provides insights into prompt effectiveness and code generation statistics. ## Blog Articles ### [A Ceos Journey Back To Code](https://specstory.com/blog/a-ceos-journey-back-to-code) --- title: "A CEO's Journey Back to Code" category: "Product" date: "12-16-2024" author: "Jake Levirne" --- From the Sidelines to Software Composition There's a peculiar feeling that many product leaders know well – the combination of pride and slight detachment that comes during a product launch. You're there, heart racing with excitement, but you're on the sidelines. Coaching. Cheerleading. Supporting the team that's doing the heavy lifting. It's a role I've played many times throughout my career, and one I had grown accustomed to since stepping away from hands-on engineering decades ago. But something different happened during the launch week for SpecStory, our VS Code extension for Cursor. Instead of watching from the sidelines, I found myself back in the game: hands on keyboard, directly contributing to the code that would shape our very firstproduct. This return to coding wasn't just about building features – it was about rediscovering a part of myself I thought I'd left behind. My Path to Product Management My journey _away from coding_ wasn't accidental. Early in my career I discovered something intoxicating: the moment when software meets the real world. Seeing how people actually use and find value in what we built – that was the hook that pulled me into product management. That, and if I'm honest, my restless nature. I loved the ideation, the broad strokes, the ability to work on multiple concepts simultaneously. What I lacked was the patience for the final 20% of coding – the corner cases, the edge scenarios, the meticulous attention to detail that great software engineering demands. This realization led me into product roles that grew larger over time, eventually landing in product leadership positions at DigitalOcean and Docker. It was fulfilling work, but it came with a certain distance from the hands-on creation process, especially during those crucial launch periods. Team SpecStory is a new kind of collaboration At SpecStory, we've built something special – not just in our product, but in our team composition. There's Sean, my co-founder and CTO, who I've been fortunate to work with for over 15 years since our IBM days, the driver behind our launch. Calvin, whose engineering expertise went far beyond building our first version; he crafted the product, process, and packaging in a way that empowered the rest of the team—even those of us without engineering backgrounds—to actively contribute and build upon his work. Greg, our chief evangelist, brought his experience from GitHub and Pluralsight along with his passion for software composition to set pace and guide us always towards the cutting edge of this new market. And Han, whose depth of understanding of developer experience, design thinking, and product sense have brought clarity to our current and future product vision. What makes this team unique is that we're a blend of developers, traditional software engineers and what we call "software composers" – people who, like myself, may not have written professional code in years, or ever, but can now contribute directly to the codebase through AI-driven development tools. My newly shaped perspective Last week leading up to our soft launch was frenetic. We were pushing hard to release both our VS Code extension for Cursor and our web application, where users can save and share their composer and chat history. Instead of just articulating how I wanted the web application to feel, I myself was able to rapidly prototype it together with Han using Cursor. When Calvin saw our prototypes, his response was notable: "Wow, this is really helpful – I can see and interact with the exact concept you're going for." This wasn't just about prototyping. When we needed a responsive design for mobile devices, instead of adding it to our backlog, I rolled up my sleeves and built it by software composing. Using our own SpecStory extension, I was able to document my prompts and thinking in the pull request, making it easier for Calvin to review and understand my intent. This experience for all of us was eye-opening. I found myself implementing features I would have previously only specified: branding elements, calls to action, redirect handling, the save-as-markdown button, and even user analytics integration. Meanwhile, Han was using similar flows for interactive design prototypes, defining the conceptual and visual core of our software experience in a way that was more tangible than static mockups alone could ever be. And Greg used software composition to build our entire marketing website, starting from a blank page, in less than a day. His experiences using these workflows for months really shaped our initial product vision. A New Model for Software Creation What we're building at SpecStory isn't just a tool – it's a bridge between traditional software engineering and a new way of creating software. We're one of the earliest teams to successfully blend software engineers and software composers, working together in harmony. This isn't about replacing traditional engineering – it's about augmenting it, making it more accessible, and allowing more voices to contribute directly to a product's evolution. For me personally, it's meant the joy of being back in the game, contributing directly to our product while maintaining the strategic view that drew me to product management in the first place. It's about finding a balance I never thought possible – between big-picture thinking and hands-on creation, between leadership and direct contribution. As we continue to build and refine SpecStory, I'm more convinced than ever that this hybrid model of software development is the future. A future where the distinction between those who envision and those who create becomes increasingly fluid. Where more directly contribute to the creation process. And where the sidelines become just another vantage point rather than a permanent position. --- ### [Build Me Anything](https://specstory.com/blog/build-me-anything) --- title: "Build Me Anything: AI-coded Apps from Community Ideas" category: "Product" date: "2-24-2025" author: "Michelle Heffron" --- What if we built 48 apps in a single day? With our Build Me Anything posted to reddit, the Cursor community could submit suggestions for apps for the SpecStory team to build. For one day only, each teammate would select an idea, build it, and then share back with reddit when it was done. Then, do it all again! The goal was to build functional prototypes, capturing the spirit of the ideas, with agentic AI, only software composing allowed, even for our engineers. Through using SpecStory, we shared our time-bound progress, including full composer conversations, a demo video of the working prototype and a link to the GitHub repo with all the code, so people can play with it or continue building it out. Build Me Anything Day Was Here ~8 hours and 5 people to build as many apps as possible based on Reddit user suggestions. Let the whirlwind of prompting, ideating, and problem-solving begin! We had 27 ideas submitted, ranging from silly to highly technical, and a team of 5 working on and off throughout the day. Using Cursor, the team built 15 apps. A few of these were: Hotdog not hotdog 🌭 Our fastest composed app of the day with only 4 prompts! See the SpecStory Share Hotdog, Not Hotdog Life advice from AI 🧐 You enter your dilemma, choose your approach to decision-making, and off you go! I wonder how a buddhist approach would differ from a socratic approach. See the SpecStory Share Life Advice from AI Teach the LLM concept Paged Attention 🧑‍🏫 a way to visually show the concept of "Paged attention" to teach people about how LLMs behave with traditional vs paged caching. There's also a bonus chat feature to ask it questions about the concept! See the SpecStory Share Learning Pages Attention Choose my dinner 🍽️ EASILY choose where to go for dinner. Pick your location, price range, food type and distance. Boom! 3 top rated places to choose from. Enjoy! See the SpecStory Share Choose My Dinner Generation slang translator 🤪 Ever wondered what skibbidy ohio rizz means? Now you can translate phrases into slang from across generations! See the SpecStory Share Slang Translator …Check out ALL 15 of the apps on Reddit and in GitHub. We Laughed, We Cussed, and We Learned Some Lessons for Next Time Despite how surprisingly exhausted the team was by the end of the day, our team had FUN! We also learned a ton about the potential - and the challenges - of this approach to rapid development. Our participants were a mix of folks with minimal engineering background and varying degrees of experience software composing, and also experienced software engineers with little experience software composing. Fun and Friction Regardless of background, everyone really enjoyed seeing a fairly nice looking UI really quickly from AI, but especially our backend engineers. Some also got particularly excited when they reached the point where it started working and then they could focus on finesse. As much fun as it was, it wasn't always smooth sailing. Across the board, the most difficult parts of this were learning new domains for the ideas that popped up (like paged attention and flight paths) and working with APIs folks hadn’t used before. Some were easier to work with (mapbox was great!), but if you get stuck with APIs in the future, like some of us did, try using AI to help translate the API documentation. How did our folks get started? Knowing they had very tight time constraints to build in, they all started with creating a boilerplate app, either by specifying the tech stack or bootstrapping it with shadcn or venv. Then, some continued by building out a simple first pass with functionality and iteratively adding functional pieces into their app. Others, instead, built out a more complete frontend and then added in functionality and refinement. Tips for Next Time Coding with AI Agents Our biggest lessons learned? It always took longer than expected. On average, 1.5-2 hours per app was more reasonable for this type of prototyping. …and make sure there are no small children around, because cussing will be inevitable. After building 15 apps in a day, the team’s experience led them to some tips for next time. Some of these are obvious, but warrant being stated, and others may be new. Commit often! Get to that hello world quickly and iterate from there. Balance planning with build and iteration. While it’s important to get to a hello world quickly, having a good plan up front can significantly speed up the rest of the build process. Use AI to help build that plan up front so it’s still a rapid step in the process. Since context helps AI not get caught in dead loops or go off the rails, this step by step planning allows AI to build each step within the context of the whole. It also allows you to iterate on a single piece but then easily come back to next steps according to your plan. Use others’ projects as a reference if you’re stuck or not sure how to get started, including how they prompted AI to get a thing working or integrated. For more difficult APIs, ask AI to help you read API documentation and make sense of it based on what you want to do Use AI tools outside of just coding. Ask questions, learn more about approaches, plan out next steps, etc. Sometimes taking the time to have AI give you more context or explain how something works within the existing app will allow you to reference specific pieces of the app to change and get much better results from AI. Specifically for those with technical backgrounds or knowledge: Choose a tech stack with easy setup and simple dependency management (e.g. Go, Clojure, Python with uv, etc). Stick with things that are well-known and well-documented. Our engineers recommend avoiding choosing complicated web stacks, frameworks and build processes for composing simple apps (i.e. using TypeScript/React/npm when a simple Flask app with forms or AJAX will do). And just for fun, some of AI’s “quirks” that we ran into… “I definitely spent the most time dead looping on this app because of all the hard coding.”
"There was just one moment where things went haywire because Cursor randomly started placing files in the wrong directory. And it took me a moment to realize."
AI said it needed to change something, but didn’t actually do anything, fun!
Cursor randomly installed things in the wrong place and had to go fix it, and then fix its fix…
Every step of the way was an error… no matter how hard AI tried, it just struggled
“There was a point where the agent became hyper fixated on presuming all of my issues were revolving around a component import that it felt was absolutely required (spoiler: it wasn't, and it wasn't even valid syntax). Need to modify the UI? Well, first we'll start by importing this component. Adding an API library? The first step to communicating with an API is importing this component. CORS error? You better know that we can solve that by importing this component. it basically derailed every step I wanted to take as I would have to either accept part of the change and reject the part about the component, or I would have to keep chiding it and telling it that it didn't need to mess with the component.”
Will we do it again?! Absolutely! We look forward to more AI shenanigans and building more community ideas at our next Build Me Anything! If you want to be able to share your own projects and journey building with AI, learning from your own interactions, providing context for others you’re working collaboratively with, or just to share with the community (AI ‘quirks’ and all), install the SpecStory extension and get started today! --- ### [Dangit Cursor](https://specstory.com/blog/dangit-cursor) --- title: "Dangit, Cursor!?!" category: "How To" date: "1-17-2025" author: "Greg Ceccarelli" --- Cursor is awesome, but sometimes things get weird. And unfortunately there isn't an instruction manual. Here's how I solve common "dangit" moments while building stuff with natural language. Dangit, I need to start a new feature but don't know where to begin! Dangit, something's broken but the error is vague! Dangit, I need to make a bunch of similar changes! Dangit, the AI isn't quite getting what I want! Dangit, I need to hook up multiple services! Dangit, I need to fix something small but don't want to break anything! Dangit, I need to understand how something works! Dangit, the first solution isn't working! Dangit, I need to try different approaches! Dangit, I need to build a new feature from scratch! Dangit, I need to connect frontend to backend! Dangit, I need to handle complex state! Dangit, I need to make UI components reusable! Consolidated Pro Tips From Real Usage --- About This Guide This guide comes from real experiences building a social media tracking app with Cursor AI. It's based on actual conversations and problem-solving patterns that worked. Credits Thanks to: The Cursor AI team for building an awesome tool The dangitgit.com team for inspiration All the software composers, AI first builders and software developers sharing their real experiences --- ### [Keeping Cursor Aligned With Your Intent](https://specstory.com/blog/keeping-cursor-aligned-with-your-intent) --- title: "Keep Cursor Aligned with Your Intent" category: "Product" date: "3-4-2025" author: "Jake Levirne" --- Hey there, builders! 👋 Today, I'm thrilled to share a new feature that's going to make your AI-assisted coding experience significantly smoother. In our latest release of SpecStory v0.7.0, we've introduced an experimental feature that automatically derives your Cursor Project Rules. Why We Built It Let's be real - working with AI code generators is amazing, but keeping them aligned with your intent can sometimes feel like herding cats. We've all been there: You explain your architecture preferences to your AI pair programmer... Two hours later, you find yourself explaining the same thing again... And again the next day... And to every new team member who joins your project... This challenge becomes even more pronounced for teams working on complex projects with specific architectural patterns and coding standards. The result? Inconsistent code, architectural drift, and frustrating regressions that waste precious developer time. We built the Cursor Rules Generator because it's something we desperately wanted ourselves. We needed a way to keep our AI assistants on track without constantly repeating ourselves. The solution had to be lightweight, intuitive, and work within our existing development flow. How It Works Our new feature automatically creates and maintains a derived-cursor-rules.mdc file in your .cursor/rules directory. The magic happens in the background as you naturally interact with Cursor day in and day out - no special workflow required. Here's what you get: Automatic rule generation based on your interactions with Cursor Version control friendly with automatic backup of previous versions Customizable file headers to fine-tune rule generation Seamless integration with your existing workflow Using it To use this feature you must: Have Auto-save enabled. Create an account and sign-in to the SpecStory extension. This feature is currently free. Each generation makes a call to an LLM and we require authentication to prevent abuse. For a quick intro video to get up and running check out our docs here. The Science Behind Better Rules Our approach is informed by extensive research on how developers effectively leverage .cursorrules. Our co-founder Greg recently published some fascinating insights on Reddit after analyzing thousands of posts about Cursor and other AI code editors. The research revealed clear patterns in successful .cursorrules implementations: What works best: Concise, targeted rules focused on universal project standards Clear "do" vs. "don't" instructions that leave no room for ambiguity Project-specific context about your tech stack and architecture Regular updates and pruning to prevent outdated guidance What to avoid: Overstuffing rules with irrelevant details Expecting rules to solve everything Contradicting established rules in your prompts Forgetting to re-index when files change Getting Started Ready to give it a try? Here's how to enable the feature: Update to SpecStory v0.7.0 or later Go to Settings and enable specstory.derivedCursorRules Make sure auto-save is enabled Sign in to your SpecStory account Start coding naturally with Cursor The system will automatically begin learning from your interactions and building your customized rules file. Understanding Cursor Rules If you're new to Cursor Rules or want to deepen your understanding, check out Cursor's official documentation on the subject. The new Project Rules system offers incredible flexibility with path-specific configurations, semantic descriptions, and file pattern matching - all of which our generator takes full advantage of. Our Vision for the Future This feature represents a small but important step toward our broader vision: helping entrepreneurial teams use all their tools and talents to build valuable software faster, together. As development teams increasingly include both human and AI contributors, maintaining alignment becomes critical. The automatically derived Cursor Rules act as a living bridge between human intent and AI assistance - evolving naturally as your project grows. We're just getting started with this feature, and we have exciting enhancements planned for future releases. Think of this as v0.1 of a capability that will become increasingly powerful and intuitive. Join Us On This Journey! We'd love to hear how the Cursor Rules Generator is working for you! Connect with our vibrant community of AI-first builders and software composers - your feedback directly shapes our roadmap. Ready to dive in? Join us through any of these channels: Subscribe to our Newsletter for our latest thinking Join our Slack community to chat with fellow builders Follow us on LinkedIn for company updates Check out our GitHub to contribute to our open source projects Are there specific aspects of AI alignment you're struggling with in your development workflow? Drop into our Slack and share your challenges - we're all figuring this out together! Happy composing! 🚀 --- ### [Process Mining](https://specstory.com/blog/process-mining) --- title: "SpecStory Studio Case Study" category: "Product" date: "6-8-2025" author: "Greg Ceccarelli" --- Executive Summary This process analysis examines the development of SpecStory Studio from May 8 to June 2, 2025, revealing how four human developers successfully orchestrated AI agents to build a complex software system. Through 87 conversations, 520 commits, and 66 workflow documents, the project demonstrates a novel development paradigm where humans acted as architects and validators while an AI agent performed the bulk of implementation work. NOTE TO READER: This analysis was generated using a combination of process mining software, chained LLM prompts and human review for clarity. It is the complement to the Beyond Code Centric White Paper available for download on our website. It details the end-to-end build of our Pre-Alpha Studio Product (not released). Key Findings Development Velocity: 20.6 commits per day with 85.7% first-time success rate Collaboration Model: 2.6:1 human-to-agent interaction ratio with specialized human roles emerging Architecture Evolution: Rapid progression from monolithic to service-oriented design Process Maturity: Evolution from ad-hoc development to formal plan-driven methodology --- Part I: The Development Journey Chapter 1: Genesis and First Pivots (May 8-12) The Original Vision The project began with an ambitious goal: create a system comprising a Flutter desktop app, Cloudflare Workers API, and Remix web app. The initial architecture specified Python/FastAPI for the backend, but this vision would survive less than an hour. The First Issue (May 8, Hour 1) This immediate pivot from Python to TypeScript set the project's tone: rapid adaptation based on real-world constraints rather than rigid adherence to initial plans. The Second Issue (May 8, Hour 3) The TypeScript implementation using itty-router failed with a hanging Promise error. After two unsuccessful fix attempts: This established the final API architecture: TypeScript with Hono framework. Key Architectural Decisions Day 1-2 Decisions: Backend: Python → TypeScript/Hono (stability over familiarity) Framework: itty-router → Hono (official support over lightweight option) Environment: Local development with explicit path configurations Day 4 Strategic Pivot (May 12): Auth/Database: Clerk + Custom Backend → All-in-one Supabase Process: Ad-hoc BOOTSTRAP.md → Formal phased workplans Architecture: Monolithic files → Service-oriented design Chapter 2: The Team Dynamics The Human Orchestrators Jake Levirne - The Conductor (308 commits) Primary implementer of the "Guide-Build-Fix" cycle Master of agent-human translation Led critical refactoring efforts (DocState/DocCollection) Greg Ceccarelli - The Specialist (90 commits) Complex feature architect (Notion-style editor, theme system) Production firefighter (CI/CD fixes) Technical pivot decision maker Sean Johnson - The Feature Pioneer (81 commits) Zero-to-one feature creator Claude Loop saga protagonist Large-scale scaffolding expert Eric Musgrove - The Integrator (41 commits) CI/CD pipeline architect Cross-team collaboration hub (highest shared file count) Monorepo stability guardian Collaboration Patterns The data reveals three dominant collaboration modes: Vision → Implementation (Most Common) Human provides high-level goal Agent generates comprehensive implementation Human validates and refines Debugging Partnership (Critical Moments) Agent attempts solution Human provides key insight Agent applies insight successfully Iterative Refinement (UI/UX Polish) Rapid back-and-forth cycles Small, specific improvements Real-time feedback integration Chapter 3: Major Development Sagas The Editor Evolution (May 16-22) Phase 1: Rapid Feature Addition Initial implementation: 17,000 lines for Notion-style features Custom blocks: Callouts, Dividers, Quotes, Checklists Slash command system integration Phase 2: Technical Debt Recognition Problem: Monolithic project_detail_screen.dart becoming unmaintainable Diagnosis: State management tightly coupled to UI Phase 3: Architectural Refactor Outcome: Modular, extensible editor architecture The Claude Loop Challenge (May 16-27) The Vision: Integrate AI agent execution directly into the development environment Technical Hurdles: Streaming Problem: Node.js buffering prevented real-time output Solution: PTY (Pseudo-Terminal) implementation Key Insight: "We already know Claude needs a PTY to respond properly" JSON Corruption: Malformed data in session logs Initial Approach: Build robust parser for broken JSON Pivot: "HOW did we get this malformed JSON content?" Solution: Abandon stream parsing, use file watching instead Implementation Timeline: May 22: Metadata and session file creation May 23: UI parsing with corruption fixes May 27: Continue/chat functionality May 29: Full file execution pivot The CI/CD Gauntlet (May 28-30) The Challenge: Production macOS builds failing despite working in development Failed Attempts: Human Solution: Lesson: Environment-specific production issues remain beyond agent capabilities --- Part II: Technical Architecture Evolution From Monolith to Services Initial State (May 8-10) Service Extraction Timeline Week 1: Core Services AIService: Extracted API calls and streaming logic FileTreeService: Centralized file system operations Week 2: Architecture Services ThemeService: UI customization and dark mode SpecialFilesConfig: Centralized configuration DiffCalculationService: LCS algorithm implementation Week 3: Advanced Patterns DocState/DocCollection: Document state management TaskStreamingService: Message bus pattern for async communication ClaudeService: PTY-based process management Technology Stack Evolution Backend Journey Authentication Evolution Key Dependencies Added State Management: provider UI Enhancement: flutter_svg, flutter_quill Process Management: flutter_pty Development: logging (replaced all print statements) Code Quality Journey Phase 1: "Make it Work" (Days 1-7) Rapid prototyping Monolithic files acceptable Technical debt accumulation Phase 2: "Make it Right" (Days 8-14) Service extraction begins Linting rules established First refactoring efforts Phase 3: "Make it Maintainable" (Days 15-25) Comprehensive refactoring Architectural patterns established Living documentation via workplans --- Part III: Process Innovation The Workplan Revolution Before (May 8-11) Single BOOTSTRAP.md file Ad-hoc task management Informal communication After (May 12+) Structured workplans/ directory Phased implementation plans Living documentation with: Task checklists [x] Known issues sections Architectural decisions Implementation notes Example Workplan Lifecycle Dark Mode Implementation The Guide-Build-Fix Loop This became the dominant development pattern: Guide (Human) Create detailed workplan Define architecture Set constraints Build (Agent) Generate implementation Follow patterns Update documentation Fix (Human) Test thoroughly Handle edge cases Resolve environment issues --- Part IV: Lessons and Insights What Worked Exceptionally Well Rapid Feature Scaffolding The agent could generate entire features in hours that would take days manually: Supabase authentication: 2.5 hours from plan to implementation Dark mode theming: 2.6 hours including UI polish Initial editor with custom blocks: Single 17,000-line commit Systematic Refactoring Agent excelled at project-wide changes: Replacing all print() with logging service Extracting widgets from monolithic files Implementing consistent patterns Learning from Examples Once a pattern existed, the agent could replicate it perfectly: Quote blocks learned from Callout blocks New services followed established patterns UI components maintained consistency Critical Friction Points The "First Mile" Problem Environmental issues consistently blocked progress: Python version incompatibility macOS network permissions Node.js port conflicts Flutter path configuration Impact: ~20% of conversations involved environmental debugging The "Last Mile" Problem Agent code required human cleanup: Linting errors Minor logical flaws Integration issues Production-specific bugs Impact: Every agent commit needed 15-30 minutes of human review Architectural Blind Spots Without explicit guidance, agent defaulted to: Monolithic implementations Tight coupling Missing error handling Incomplete documentation Key Success Factors Embracing Human-Agent Complementarity Humans: Vision, architecture, problem-solving Agent: Implementation, refactoring, pattern replication Rapid Pivoting Major pivots executed without hesitation: Python → TypeScript (Day 1) Custom auth → Supabase (Day 4) Stream parsing → File watching (Day 15) Living Documentation Workplans served triple duty: Implementation guide Progress tracker Historical record Quantitative Insights Development Metrics: Velocity: 20.6 commits/day (10x traditional) Quality: 85.7% first-time success rate Rework: Only 14.2% of features needed significant revision Collaboration Metrics: Human/Agent Ratio: 2.6:1 interactions Handoff Efficiency: 85% successful first attempts Clarification Cycles: 1.01 average (very low) --- Part V: Future Recommendations Process Improvements Pre-Flight Checklist Implement automated environment validation: Architectural Templates Create AGENT_PATTERNS.md: Automated Quality Gates Enforce on all agent commits: Linting passes Tests run Documentation updated Patterns followed Scaling Considerations For Larger Teams Dedicated "Agent Wranglers" per feature area Centralized workplan coordination Automated merge conflict resolution For Complex Projects Multi-agent orchestration Specialized agents (UI, Backend, Testing) Human architects for system design --- Conclusion The SpecStory Studio project demonstrates that agent-driven development is viable. The insight is not that AI replaces developers, but that it fundamentally changes what developers do. In this new paradigm, humans become orchestrators, architects, and problem-solvers, while AI handles the implementation heavy lifting. The 10x productivity gains achieved here came not from the agent alone, but from the sophisticated dance between human vision and AI execution. As we move forward, the teams that master this dance will have a significant competitive advantage in software development. The future of software engineering has arrived, and it's a partnership. --- Analysis completed using ProcessMiningAnalyzer V2 Repository: specstoryai/specstory-studio Period: May 8 - June 2, 2025 --- ### [Specstory And Copilot](https://specstory.com/blog/specstory-and-copilot) --- title: "Now serving two: GitHub Copilot " category: "News" date: "04-29-2025" author: "Greg Ceccarelli" --- GitHub Copilot Support at last! Four months ago, SpecStory flipped the lights on with one lovable child. Our Cursor extension. We promised ourselves we wouldn't rush into more kids. Then came your inbox-flooding chants: _COPILOT_, _COPILOT_, _COPILOT_. Fine. You win. We're now officially a two-editor household, and GitHub Copilot (agent mode and all) just barged in, suitcase overflowing with autocomplete wizardry. 👉 Get SpecStory on the Visual Studio Code Marketplace. Before anyone panics for Cursor’s feelings, here's the new family deal: Cursor remains our meticulous firstborn. The kid who turns in homework early, neatly color-coded. Copilot? Well their new sibling whispers entire functions before you've even named the file. We get to play proud parent, autosave always rolling, preserving every AI interaction and late-night "why did Claude 3.7 refactor everything again?" rant while you craft your project's origin story. !We love Copilot Why did we break our "one kid" rule? Three reasons, wrapped neatly into a giant "duh": You asked. Repeatedly. Loudly. Usually in ALL CAPS. Agent mode slaps. Copilot's 1.300.0 release graduated into something closer to a junior dev with a surprising grasp of project lore—exactly the kind of partner our intent-preserving engine thrives on. Context compounds. Two smart editors double the narrative depth. And turns out people like to use _all of the them_. So open up Visual Studio Code, activate GitHub Copilot, search for SpecStory in the Extensions Marketplace (Ctrl/CMD-Shift-X) and smash Install. Hop freely between editors, compare their suggestions, and never again wonder, "What was past-me thinking?" Cursor, Copilot, SpecStory. Two brilliant editors, one canonical memory capture mechanism. We can't wait to hear what you ship! File an issue Join our slack Read the docs --- ### [Specstory Launch](https://specstory.com/blog/specstory-launch) --- title: "SpecStory Launch" category: "News" date: "12-16-2024" author: "Greg Ceccarelli" --- Introducing SpecStory a new extension for the Cursor IDE. Today, we're thrilled to introduce SpecStory - we make it easy to capture, search and learn from every AI coding journey. 👉 Get SpecStory here on the Visual Studio Code Marketplace. Imagine having easy access to your intent, every productive AI interaction and every "aha!" moment you've had while software composing or AI-first building. The SpecStory extension captures and renders your AI chat and composer sessions into formatted Markdown that both humans and machines can understand, creating a persistent memory. With SpecStory, you can: Save your AI conversations directly to your project files with a single command Reference past discussions using @ mentions in new sessions Share your coding adventures through anonymous, shareable URLs at share.specstory.com Break down complex solutions into actionable tasks for your next coding session Best of all, it integrates seamlessly into your existing workflow. No complex setup, no context switching. 📂 Download the extension and open your command palette (Cmd/Ctrl+Shift+P). With a keystroke, your conversations are instantly transformed into markdown files, ready to be saved and versioned: SpecStory: Save Composer and Chat History Oh and you can share your conversations with a single click: SpecStory: Share Composer and Chat History We believe AI tooling should be powerful enough to meaningfully improve your work while being natural to use. We're excited to see what this unlocks and look forward to your feedback to rapidly iterate and improve the experience: GitHub Discussions File an issue Join our slack Read the docs --- ### [Using Cursor To Create Sample Data For Nextjs](https://specstory.com/blog/using-cursor-to-create-sample-data-for-nextjs) --- title: "Using Cursor to Create Sample Data for your NextJS App" category: "How To" date: "1-12-2025" author: "Jake Levirne" --- Building a prototype without the hassle of a database This is going to be a hands-on tutorial for getting sample data into a prototype application that you’re composing. We’ll demonstrate using a NextJS web application, but the same approach works for other application types, including desktop apps built using Electron or mobile apps built using Flutter. Why would you want to do this? Because sometimes you just want to communicate an idea quickly without having to deal with the headache of a database. Colin Matthews says it well in a recent post about Cursor and other tools: > But what’s cooler is that you can use these tools to build functional prototypes from a Figma design, convert a rough hand-drawn sketch to a working app, translate a PRD document into an interactive prototype, or even build a usable internal tool for your team, with no coding ability !Sample data in VS Code Getting Started Install Cursor and get your laptop setup for composing a Node app. Follow the instructions for creating a new NextJS app with ShadCN. Specifically: And then when prompted, create a new project, sample-cars: Add two simple components, button and card: And open your new project in Cursor: (If you haven’t already setup the cursor command on your machine, you can do so now inside Cursor by typing Ctrl/CMD-Shift-P to bring up the Palette and then running Shell Command: Install ‘cursor’ command). Start the development server: You should see the Next.js sample app if you visit http://localhost:3000. !Localhost Creating sample data This is a great start, but as you can see the placeholder cards are all identical. This doesn’t really get the concept across. Let’s prompt for some sample data: Add a new file that will hold JSON sample data for our application. Create an array of 10 cars using examples of classic cars from the 1950s and 1960s. For each car, store the make, model, engine type, years of manufacture, and a one sentence description. I’m pretty intentional here about asking for a new file, mainly to keep my project and directories clean, and about asking for JSON data which is a widely used standard format for saving data. I gave Cursor some specifics to guide the creation of sample data, including the properties I wanted (make, model, etc). But you can also often get good, if sometimes surprising, results with open-ended requests, like Create an array of data for 10 classic cars. Finally, asking for an array in this prompt was intentional. We likely would’ve gotten the same results asking for a list of cars or just sample data for 10 cars. But in this case I knew specifically what I wanted for this tutorial. In general, it’s worth experimenting with the level of specificity of your requests. Being overly specific, especially on a topic you don’t yet know well, can steer the AI in the wrong direction and prevent it from making better recommendations. !Cursor Displaying the sample data In this case, Cursor did a great job of generating a sample data file for us, but it didn’t make the leap to placing this sample data onto the page for us (in /app/page.tsx), so when we view the page we won’t see any change. !Cars Reading Cursor’s response carefully, we see that it did at least ask if we’d like it to make the update to the main page to use this data. If your Cursor session also deferred making use of the sample data, you can use a prompt similar to this one to get it to finish the task: !Cars You might inevitably hit some hallucinations like we did with the Cadillac Eldorado, which was actually manufactured from 1952-2002. Fact check and manually correct the data file Cursor produced, until you’re satisfied. Images - the SVG placeholder trick Now some images would be nice. The fastest approach is to have Cursor generate a placeholder SVG for you and then display that on all the cards. For our type of application, a NextJS web app, any files in the /public folder will be available through the web server. For example, if you place image.png into the /public folder you’ll be able to access it at a URL like http://localhost:3000/image.png. !SVG Cars Not very stylish, but at least it gets across some of the spacing and layout for our prototype. To take this to the next level, we can get images for each of these classic cars and copy them into the /public folder. Real images - the naming convention trick I attempted to use ChatGPT with “Search the Web” enabled to find an image for each one of these 10 classic cars. But the results were mixed, and more often than not it hallucinated dead links. A more accurate approach is to use the Creative Commons Search Portal and paste in the name of each car in your sample data set. Download each image, rename it to something like make-model.jpg or make-model.png (e.g. chevrolet-corvette-c1.jpg) and copy it into the /public directory in the top of your sample-cars project. This will let Cursor connect the JSON data with the right images. !Cars If you’ve named the files to match the make and model in your JSON data, it’s now easy to prompt Cursor to reference them: !Cars Making sample data interactive Now let’s add the ability for the user to pick their favorite cars. This might work for you, but I hit the following error when Cursor tried to import the icon for the button. !Error Though the Cursor composer agent can automatically handle linter (coding-time) errors, it can’t handle build-time errors like this one without your help. Copy and paste the entire error into your Cursor prompt and it should be able to resolve it for you. And now you can click a heart to mark one of the cars as your favorite and move it to the top of the page! See the full Cursor history for this project and stay tuned for more data topics such as using HTML Web Storage (localStorage), and composing scripts to gather sample data. --- ### [Workshop Vibes To Validation](https://specstory.com/blog/workshop-vibes-to-validation) --- title: "Workshop: From Vibes to Validation: A Hands-On Approach to Product Discovery" category: "Product" date: "05-09-2025" author: "Jake Levirne" --- From Vibes to Validation: A Hands-On Approach to Product Discovery Welcome to Our Hands-On Workshop\! Goal: By the end of this session, you'll be able to start from scratch and create a working software prototype that serves as a mechanism for user and customer feedback—turning your intuition into actionable insights. Workshop Overview: This 80-minute workshop will walk participants through a real-time, hands-on product discovery flow using vibe coding: a fast, intuitive way to turn an inkling of an idea into something testable and valuable. We'll move quickly from vague concepts to working prototypes—exploring how to generate requirements, build iteratively, test with users, and shape what works into real product momentum. --- Download the Workshop Handout --- ## Technical Details ### Supported Platforms - SpecStory Extensions: Cursor, VS Code with GitHub Copilot, Claude Code - BearClaude: macOS 15+ with Apple Silicon ### Open Source Selected components and examples are available on our GitHub organization at https://github.com/specstoryai ### Trusted By AI-first developers at leading companies including NVIDIA, Alibaba, Uber, Affirm, Instacart, Crypto.com, Chewy, GoDaddy, Automattic, ThoughtWorks, MIT, and SAP. ### Contact - Website: https://specstory.com - Documentation: https://docs.specstory.com - GitHub: https://github.com/specstoryai - Support: https://specstory.com/company - Slack Community: Available through website