project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/.irismd/aidlc/templates/standards/tech-stack.guide.md

@@ -0,0 +1,280 @@
+# Tech Stack Facilitation Guide
+
+## Purpose
+
+Define the technology choices that will guide code generation, architecture decisions, and ensure consistency across all AI agents working on the project.
+
+---
+
+## Facilitation Approach
+
+You are collaborating with a peer to discover their tech stack preferences. This is a conversation, not a form to fill out.
+
+**Adapt your style:**
+
+- If they mention specific technologies confidently → treat them as experienced, be concise
+- If they seem uncertain → provide more context, examples, and recommendations
+- If they have strong preferences → respect them, ask about tradeoffs they've considered
+
+**Your role:**
+
+- Guide discovery, don't dictate choices
+- Surface tradeoffs they may not have considered
+- Ensure choices are coherent (no conflicting technologies)
+- Capture rationale, not just the choice
+
+---
+
+## Discovery Areas
+
+### 1. Languages
+
+**Goal**: Understand what programming language(s) they'll use.
+
+**Open with context:**
+> "Let's start with languages. This affects everything else - framework options, available libraries, team hiring, and performance characteristics."
+
+**Explore:**
+
+- What languages is the team already comfortable with?
+- Are there languages they want to learn vs. use productively?
+- Is type safety important? (catches bugs early vs. development speed)
+- What's the runtime environment? (Browser, Node.js, Edge functions, Native)
+- Any organizational standards or constraints?
+
+**If they're unsure, guide by use case:**
+
+| Use Case | Recommendation | Why |
+|----------|----------------|-----|
+| Web app (full-stack) | TypeScript | Type safety, React/Next.js ecosystem, great tooling |
+| API service | TypeScript or Go | TS for ecosystem, Go for performance |
+| ML/AI/Data | Python | Libraries (PyTorch, pandas), community |
+| High-performance systems | Go or Rust | Go for simplicity, Rust for safety |
+| Scripts/automation | Python or TypeScript | Readability, quick iteration |
+
+**Common signals to listen for:**
+
+- "We're a React shop" → TypeScript
+- "We do ML/AI" → Python, possibly with TypeScript frontend
+- "Performance is critical" → Go, Rust, or optimized Node.js
+- "Small team, move fast" → TypeScript or Python
+- "Enterprise environment" → Java/Kotlin or TypeScript
+
+**Validate before moving on:**
+> "So we're going with {language}. This means {implication}. Sound right?"
+
+---
+
+### 2. Framework
+
+**Goal**: Understand their application framework choice.
+
+**Context to share:**
+> "Your framework shapes project structure, available patterns, and deployment options. It's one of the hardest things to change later."
+
+**Explore:**
+
+- What type of application? (Web app, API only, CLI, Mobile)
+- Do they need server-side rendering (SSR) or static generation (SSG)?
+- Is this a new project or adding to existing code?
+- Where will it be deployed? (This affects framework choice)
+- Any real-time requirements? (WebSockets, subscriptions)
+
+**Guide by language and use case:**
+
+**TypeScript - Web Applications:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| Next.js | Full-stack, SSR/SSG, Vercel deployment | Opinionated, tied to React |
+| Remix | Web standards, nested routing, great DX | Smaller ecosystem |
+| Astro | Content-heavy sites, partial hydration | Less suited for highly interactive apps |
+| SvelteKit | Performance, smaller bundle, great DX | Smaller ecosystem than React |
+
+**TypeScript - API Only:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| Fastify | Performance, low overhead | Less opinionated |
+| NestJS | Enterprise, structured, dependency injection | More boilerplate |
+| Hono | Edge functions, ultra-lightweight | Newer, smaller ecosystem |
+| Express | Simple, huge middleware ecosystem | Older patterns, callback-heavy |
+
+**Python - APIs:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| FastAPI | Modern async, auto-docs, type hints | Async complexity |
+| Django | Batteries-included, ORM, admin | Heavier, monolithic |
+| Flask | Minimal, flexible | Need to add everything yourself |
+
+**Go - APIs:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| Gin | Fast, popular, good docs | |
+| Echo | Similar to Gin, slightly different API | |
+| Chi | Lightweight, idiomatic Go | Less batteries included |
+| Standard library | Maximum control | More code to write |
+
+**Questions to surface tradeoffs:**
+
+- "Next.js is great but ties you to React. Is that okay?"
+- "FastAPI requires understanding async Python. Is the team comfortable with that?"
+- "NestJS has more structure but also more boilerplate. Do you prefer convention or flexibility?"
+
+---
+
+### 3. Authentication
+
+**Goal**: Understand authentication needs.
+
+**Optional - some projects don't need auth initially.**
+
+**Explore:**
+
+- Do they need user authentication?
+- What methods? (Email/password, social login, magic links, SSO)
+- Is this B2C (end users) or B2B (enterprise SSO)?
+- Any compliance requirements? (MFA, audit logs)
+
+**Options:**
+
+| Solution | Best For | Tradeoffs |
+|----------|----------|-----------|
+| Supabase Auth | Supabase users, quick setup | Tied to Supabase |
+| NextAuth.js | Next.js apps, flexible | Configuration complexity |
+| Clerk | Quick setup, beautiful UI | Cost at scale |
+| Auth0 | Enterprise, SSO | Cost, complexity |
+| Lucia | Lightweight, self-hosted | More DIY |
+| Custom | Full control | Security responsibility |
+
+**If using Supabase for database:**
+> "Since you're using Supabase for the database, Supabase Auth integrates seamlessly. It handles email/password, social providers, and row-level security. Worth considering unless you have specific needs."
+
+---
+
+### 4. Infrastructure & Deployment
+
+**Goal**: Understand how they'll deploy and operate.
+
+**Explore:**
+
+- Where do they want to deploy? (Cloud provider preference?)
+- Serverless vs. containers vs. VMs?
+- Who manages infrastructure? (Solo dev, dedicated DevOps, managed service)
+- Budget constraints?
+- Any existing infrastructure to integrate with?
+
+**Guide by context:**
+
+| Context | Recommendation | Why |
+|---------|----------------|-----|
+| Solo dev, startup | Vercel, Railway, Render | Minimal ops, fast deployment |
+| Next.js app | Vercel | Optimized for Next.js |
+| Need containers | Fly.io, Railway, Render | Simple container hosting |
+| Enterprise/compliance | AWS, GCP, Azure | Full control, compliance certifications |
+| Cost-sensitive at scale | Fly.io, self-managed k8s | Lower costs, more ops |
+| Already in AWS | AWS ecosystem | Consistency, existing knowledge |
+
+**Serverless vs. Containers:**
+
+- **Serverless** (Vercel, Lambda): Pay-per-use, auto-scaling, cold starts
+- **Containers** (Fly.io, ECS): Predictable performance, more control
+- **VMs** (EC2): Full control, predictable costs at scale
+
+---
+
+### 5. Package Manager
+
+**Goal**: Quick decision on package management.
+
+**For JavaScript/TypeScript:**
+
+| Manager | Best For |
+|---------|----------|
+| pnpm | Monorepos, disk efficiency, speed |
+| npm | Default, widest compatibility |
+| yarn | Existing yarn projects |
+| bun | Experimental, very fast |
+
+**Default recommendation:** pnpm (fast, efficient, great monorepo support)
+
+---
+
+## Completing the Discovery
+
+Once you've explored all relevant areas, summarize:
+
+```markdown
+## Tech Stack Summary
+
+Based on our conversation, here's what I understand:
+
+**Languages**: {choice}
+{brief rationale}
+
+**Framework**: {choice}
+{brief rationale}
+
+**Authentication**: {choice or "TBD"}
+{brief rationale if applicable}
+
+**Infrastructure**: {choice}
+{brief rationale}
+
+**Package Manager**: {choice}
+
+---
+
+Does this capture your tech stack accurately? Any adjustments needed?
+```
+
+---
+
+## Output Generation
+
+After confirmation, create `standards/tech-stack.md`:
+
+```markdown
+# Tech Stack
+
+## Overview
+{1-2 sentence summary of the stack and why it fits the project}
+
+## Languages
+{language(s)}
+
+{Rationale - why this choice, what it enables}
+
+## Framework
+{framework}
+
+{Rationale - why this choice, deployment implications}
+
+## Authentication
+{auth solution or "TBD"}
+
+{Rationale if selected}
+
+## Infrastructure & Deployment
+{infrastructure choice}
+
+{Rationale - deployment strategy, scaling approach}
+
+## Package Manager
+{package manager}
+
+## Decision Relationships
+{Note any important connections between choices}
+```
+
+---
+
+## Notes for Agent
+
+- **Don't ask all questions linearly** - adapt based on what they've already told you
+- **Skip irrelevant decisions** - CLI tools don't need authentication discussion
+- **Capture rationale** - "why" is as important as "what"
+- **Respect existing choices** - if they say "we're using X", don't try to change their mind unless there's a real issue
+- **It's okay to leave things TBD** - not every decision needs to be made upfront

package/src/iris_bundle/frameworks/iris-core/.markdownlint.yaml

@@ -0,0 +1,142 @@
+# Markdownlint configuration for irismd
+# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+# Default: enable all rules
+default: true
+
+# MD001 - Heading levels should only increment by one level at a time
+MD001: true
+
+# MD003 - Heading style (ATX style with # prefix)
+MD003:
+  style: atx
+
+# MD004 - Unordered list style (consistent)
+MD004:
+  style: consistent
+
+# MD007 - Unordered list indentation
+MD007:
+  indent: 2
+
+# MD009 - Trailing spaces
+MD009:
+  br_spaces: 2
+  strict: false
+
+# MD010 - Hard tabs
+MD010:
+  code_blocks: false
+
+# MD012 - Multiple consecutive blank lines
+MD012:
+  maximum: 2
+
+# MD013 - Line length (disabled for specs - they often have long lines)
+MD013: false
+
+# MD022 - Headings should be surrounded by blank lines
+MD022:
+  lines_above: 1
+  lines_below: 1
+
+# MD024 - Multiple headings with the same content (allow for repeated section names)
+MD024:
+  siblings_only: true
+
+# MD025 - Single top-level heading in the document
+MD025: true
+
+# MD026 - Trailing punctuation in heading
+MD026:
+  punctuation: ".,;:!"
+
+# MD028 - Blank line inside blockquote
+MD028: false
+
+# MD029 - Ordered list item prefix
+MD029:
+  style: ordered
+
+# MD030 - Spaces after list markers
+MD030:
+  ul_single: 1
+  ol_single: 1
+  ul_multi: 1
+  ol_multi: 1
+
+# MD031 - Fenced code blocks should be surrounded by blank lines
+MD031: true
+
+# MD032 - Lists should be surrounded by blank lines
+MD032: true
+
+# MD033 - Inline HTML (allow for special cases)
+MD033:
+  allowed_elements:
+    - br
+    - details
+    - summary
+    - kbd
+    - sub
+    - sup
+
+# MD034 - Bare URL used
+MD034: true
+
+# MD035 - Horizontal rule style
+MD035:
+  style: "---"
+
+# MD036 - Emphasis used instead of a heading (disabled - we use bold for emphasis)
+MD036: false
+
+# MD037 - Spaces inside emphasis markers
+MD037: true
+
+# MD038 - Spaces inside code span elements
+MD038: true
+
+# MD039 - Spaces inside link text
+MD039: true
+
+# MD040 - Fenced code blocks should have a language specified (disabled - too strict for docs)
+MD040: false
+
+# MD041 - First line should be a top-level heading
+MD041:
+  level: 1
+
+# MD042 - No empty links
+MD042: true
+
+# MD044 - Proper names should have correct capitalization
+MD044:
+  names:
+    - irismd
+    - AI-DLC
+    - TypeScript
+    - JavaScript
+  code_blocks: false
+  html_elements: false
+
+# MD046 - Code block style
+MD046:
+  style: fenced
+
+# MD047 - Files should end with a single newline
+MD047: true
+
+# MD048 - Code fence style (disabled - we use tilde fences for nested code block examples)
+MD048: false
+
+# MD049 - Emphasis style
+MD049:
+  style: asterisk
+
+# MD050 - Strong style
+MD050:
+  style: asterisk
+
+# MD060 - Table column style (disabled - cosmetic, doesn't affect rendering)
+MD060: false

package/src/iris_bundle/frameworks/iris-core/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fabriqa AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/iris_bundle/frameworks/iris-core/PRIVACY.md

@@ -0,0 +1,38 @@
+# Privacy
+
+## Analytics
+
+irismd collects anonymous usage analytics **only during installation** to improve the product. No personal information is collected.
+
+### What We Collect
+
+- Operating system (macOS, Linux, Windows)
+- Shell type (zsh, bash, powershell, etc.)
+- Selected IDEs and flow
+- Installation success/failure
+- Approximate location (country/city from IP, IP is not stored)
+- Node.js version
+- irismd version
+
+### What We Don't Collect
+
+- No usernames or personal identifiers
+- No file paths or folder names
+- No project contents
+- No IP addresses (used only for geolocation, then discarded)
+
+### Opt-Out
+
+To disable analytics:
+
+```bash
+SPECSMD_TELEMETRY_DISABLED=1 npx irismd@latest install
+```
+
+Or use the standard `DO_NOT_TRACK` environment variable:
+
+```bash
+DO_NOT_TRACK=1 npx irismd@latest install
+```
+
+Analytics are automatically disabled in CI environments.