owflow 0.1.1 → 0.1.3

package/dist/skills/docs-manager/docs/standards/frontend/accessibility.md

@@ -0,0 +1,25 @@
+## Accessibility
+
+### Semantic HTML
+Use appropriate elements (nav, main, button) that convey meaning to assistive technologies.
+
+### Keyboard Navigation
+Make all interactive elements accessible via keyboard with visible focus indicators.
+
+### Color Contrast
+Maintain 4.5:1 contrast for normal text; don't rely solely on color to convey information.
+
+### Alt Text and Labels
+Provide descriptive alt text for images and labels for form inputs.
+
+### Screen Reader Testing
+Verify all views work with screen readers.
+
+### ARIA When Needed
+Use ARIA attributes to enhance complex components when semantic HTML isn't enough.
+
+### Heading Structure
+Use heading levels (h1-h6) in proper order for clear document outline.
+
+### Focus Management
+Manage focus appropriately in dynamic content, modals, and SPAs.

package/dist/skills/docs-manager/docs/standards/frontend/components.md

@@ -0,0 +1,28 @@
+## Components
+
+### Single Responsibility
+Each component should do one thing well.
+
+### Reusability
+Design components to work across different contexts with configurable props.
+
+### Composability
+Build complex UIs by combining smaller components rather than creating monoliths.
+
+### Clear Interface
+Define explicit, documented props with sensible defaults.
+
+### Encapsulation
+Keep implementation details private; expose only what's necessary.
+
+### Consistent Naming
+Use descriptive names that indicate purpose and follow team conventions.
+
+### Local State
+Keep state as close to where it's used as possible; lift only when needed.
+
+### Minimal Props
+If a component needs many props, consider composition or splitting it.
+
+### Documentation
+Document usage, props, and examples to help team adoption.

package/dist/skills/docs-manager/docs/standards/frontend/css.md

@@ -0,0 +1,16 @@
+## CSS
+
+### Consistent Methodology
+Stick to the project's chosen approach (Tailwind, BEM, CSS modules, etc.) across the entire codebase.
+
+### Work With the Framework
+Use framework patterns as intended rather than fighting them with excessive overrides.
+
+### Design Tokens
+Establish and document consistent values for colors, spacing, and typography.
+
+### Minimize Custom CSS
+Prefer framework utilities to reduce custom styling maintenance.
+
+### Production Optimization
+Use CSS purging or tree-shaking to remove unused styles.

package/dist/skills/docs-manager/docs/standards/frontend/responsive.md

@@ -0,0 +1,28 @@
+## Responsive Design
+
+### Mobile-First
+Start with mobile layout and progressively enhance for larger screens.
+
+### Standard Breakpoints
+Use consistent breakpoints (mobile, tablet, desktop) across the application.
+
+### Fluid Layouts
+Use percentage-based widths and flexible containers that adapt to screen size.
+
+### Relative Units
+Prefer rem/em over fixed pixels for better scalability.
+
+### Cross-Device Testing
+Test across multiple screen sizes to ensure a balanced experience.
+
+### Touch-Friendly
+Size tap targets appropriately (minimum 44x44px) for mobile users.
+
+### Mobile Performance
+Optimize images and assets for mobile network conditions.
+
+### Readable Typography
+Maintain readable font sizes across all breakpoints.
+
+### Content Priority
+Show the most important content first on smaller screens.

package/dist/skills/docs-manager/docs/standards/global/coding-style.md

@@ -0,0 +1,25 @@
+## Coding Style
+
+### Naming Consistency
+Follow established naming patterns for variables, functions, classes, and files throughout the project.
+
+### Automatic Formatting
+Use automated tools to enforce consistent indentation, spacing, and line breaks.
+
+### Descriptive Names
+Choose names that clearly communicate intent; avoid cryptic abbreviations or single-letter identifiers outside tight loops.
+
+### Focused Functions
+Write functions that do one thing well; smaller functions are easier to read, test, and maintain.
+
+### Uniform Indentation
+Standardize on spaces or tabs and enforce with editor/linter settings.
+
+### No Dead Code
+Remove unused imports, commented-out blocks, and orphaned functions instead of leaving them behind.
+
+### No Backward Compatibility Unless Required
+Avoid extra code paths for backward compatibility unless explicitly needed.
+
+### DRY (Don't Repeat Yourself)
+Extract repeated logic into reusable functions or modules.

package/dist/skills/docs-manager/docs/standards/global/commenting.md

@@ -0,0 +1,10 @@
+## Commenting
+
+### Let Code Speak
+Write code that explains itself through structure and naming.
+
+### Comment Sparingly
+Add brief comments only when the logic isn't self-evident from the code.
+
+### No Change Comments
+Avoid comments about recent fixes or changes; comments should be timeless explanations, not changelogs.

package/dist/skills/docs-manager/docs/standards/global/conventions.md

@@ -0,0 +1,31 @@
+## Development Conventions
+
+### Predictable Structure
+Organize files and directories in a logical, navigable layout.
+
+### Up-to-Date Documentation
+Keep README files current with setup steps, architecture overview, and contribution guidelines.
+
+### Clean Version Control
+Write clear commit messages, use feature branches, and add meaningful descriptions to pull requests.
+
+### Environment Variables
+Store configuration in environment variables; never commit secrets or API keys.
+
+### Minimal Dependencies
+Keep dependencies lean and up-to-date; document why major ones are included.
+
+### Consistent Reviews
+Follow a defined code review process with clear expectations for reviewers and authors.
+
+### Testing Standards
+Define required test coverage (unit, integration, etc.) before merging.
+
+### Feature Flags
+Use flags for incomplete features instead of long-lived branches.
+
+### Changelog Updates
+Maintain a changelog or release notes for significant changes.
+
+### Build What's Needed
+Avoid speculative code and "just in case" additions (see minimal-implementation.md).

package/dist/skills/docs-manager/docs/standards/global/error-handling.md

@@ -0,0 +1,22 @@
+## Error Handling
+
+### Clear User Messages
+Show helpful, actionable messages without exposing internal details or security-sensitive information.
+
+### Fail Fast
+Validate inputs and check preconditions early; reject invalid data before it causes deeper issues.
+
+### Typed Exceptions
+Use specific exception types instead of generic ones to enable precise error handling.
+
+### Centralized Handling
+Catch and process errors at appropriate boundaries (controllers, API layers) rather than scattering try-catch throughout.
+
+### Graceful Degradation
+When non-critical services fail, continue operating with reduced functionality rather than crashing entirely.
+
+### Retry with Backoff
+Use exponential backoff for transient failures when calling external services.
+
+### Resource Cleanup
+Always release resources (file handles, connections) in finally blocks or equivalent cleanup mechanisms.

package/dist/skills/docs-manager/docs/standards/global/minimal-implementation.md

@@ -0,0 +1,22 @@
+## Minimal Implementation
+
+### Build What You Need
+Create only methods, classes, and functions that will actually be called.
+
+### Clear Purpose
+Every method should either be called or improve code readability; nothing else.
+
+### Delete Exploration Artifacts
+Remove helper methods and utilities created during development that ended up unused.
+
+### No Future Stubs
+Avoid empty methods, placeholder functions, or interfaces "for future extensibility".
+
+### No Speculative Abstractions
+Skip factories, strategies, or adapters unless there's an immediate need.
+
+### Review Before Commit
+Verify all new methods have callers or serve a clear readability purpose before completing a task.
+
+### Unused Code Is Debt
+Remove dead code promptly; it confuses readers and adds maintenance burden.

package/dist/skills/docs-manager/docs/standards/global/validation.md

@@ -0,0 +1,28 @@
+## Validation
+
+### Server-Side Always
+Validate on the server; client-side validation alone is insufficient for security and data integrity.
+
+### Client-Side for Feedback
+Use client-side validation for immediate user feedback, but duplicate checks server-side.
+
+### Validate Early
+Check inputs as early as possible and reject invalid data before processing.
+
+### Specific Errors
+Provide clear, field-specific messages that help users correct their input.
+
+### Allowlists Over Blocklists
+Define what's allowed rather than trying to block everything else.
+
+### Type and Format Checks
+Validate data types, formats, ranges, and required fields systematically.
+
+### Input Sanitization
+Sanitize user input to prevent injection attacks (SQL, XSS, command injection).
+
+### Business Rules
+Validate business logic (sufficient balance, valid dates) at the appropriate layer.
+
+### Consistent Enforcement
+Apply validation uniformly across all entry points (forms, APIs, background jobs).

package/dist/skills/docs-manager/docs/standards/testing/test-writing.md

@@ -0,0 +1,25 @@
+## Test Writing
+
+### Test Behavior
+Focus on what code does, not how it does it, to allow safe refactoring.
+
+### Clear Names
+Use descriptive names explaining what's tested and expected (`shouldReturnErrorWhenUserNotFound`).
+
+### Mock External Dependencies
+Isolate tests by mocking databases, APIs, and external services.
+
+### Fast Execution
+Keep unit tests fast (milliseconds) so developers run them frequently.
+
+### Risk-Based Testing
+Prioritize testing based on business criticality and likelihood of bugs.
+
+### Balance Coverage and Velocity
+Adjust test coverage based on project needs and team workflow.
+
+### Critical Path Focus
+Ensure core user workflows and critical business logic are well-tested.
+
+### Appropriate Depth
+Match edge case testing to the risk profile of the code.

package/dist/skills/docs-manager/references/claude-md-template.md

@@ -0,0 +1,29 @@
+# AGENTS.md Documentation Section Template
+
+Add this section to the project's `AGENTS.md` file. Place it prominently near the top. Verify the INDEX.md path is correct and the file exists before adding.
+
+```markdown
+## Coding Standards & Conventions
+
+Read @.owflow/docs/INDEX.md before starting any task. It indexes the project's coding standards and conventions:
+
+- Coding standards organized by domain (frontend, backend, testing, etc.)
+- Project vision, tech stack, and architecture decisions
+
+Follow standards in `.owflow/docs/standards/` when writing code — they represent team decisions. If standards conflict with the task, ask the user.
+
+### Standards Evolution
+
+When you notice recurring patterns, fixes, or conventions during implementation that aren't yet captured in standards — suggest adding them. Examples:
+
+- A bug fix reveals a pattern that should be standardized (e.g., "always validate X before Y")
+- PR review feedback identifies a convention the team wants enforced
+- The same type of fix is needed across multiple files
+- A new library/pattern is adopted that should be documented
+
+When this happens, briefly suggest the standard to the user. If approved, invoke `/standards-update` with the identified pattern.
+
+## owflow Workflows
+
+This project uses the owflow plugin for structured development workflows. When any `/*` command is invoked, execute it via the Skill tool immediately — do not skip workflows for "straightforward" tasks. The user chose the workflow intentionally; complexity assessment is the workflow's job.
+```

package/dist/skills/docs-manager/references/index-md-template.md

@@ -0,0 +1,73 @@
+# INDEX.md Template
+
+Use this structure when generating or updating `.owflow/docs/INDEX.md`. Scan the actual `.owflow/docs/` directory to populate sections dynamically — do not hardcode file lists.
+
+For technical standards, the description MUST enumerate specific practices/conventions documented in the file, not just a generic category description.
+
+```markdown
+# Documentation Index
+
+**IMPORTANT**: Read this file at the beginning of any development task to understand available documentation and standards.
+
+## Quick Reference
+
+### Project Documentation
+
+Project-level documentation covering vision, goals, architecture, and technology choices.
+
+### Technical Standards
+
+Coding standards, conventions, and best practices organized by domain.
+
+---
+
+## Project Documentation
+
+Located in `.owflow/docs/project/`
+
+### Vision (`project/vision.md`)
+
+[Brief description of what this file contains]
+
+### Roadmap (`project/roadmap.md`)
+
+[Brief description of what this file contains]
+
+### Tech Stack (`project/tech-stack.md`)
+
+[Brief description of what this file contains]
+
+### Architecture (`project/architecture.md`)
+
+[Brief description of what this file contains - if exists]
+
+---
+
+## Technical Standards
+
+### [Category Name] Standards
+
+Located in `.owflow/docs/standards/[category]/`
+
+#### [Standard Name] (`standards/[category]/[name].md`)
+
+[Practice-specific description — enumerate actual conventions, not generic text]
+
+[... repeat for all categories and standards discovered in the directory ...]
+
+---
+
+## How to Use This Documentation
+
+1. **Start Here**: Always read this INDEX.md first to understand what documentation exists
+2. **Project Context**: Read relevant project documentation before starting work
+3. **Standards**: Reference appropriate standards when writing code
+4. **Keep Updated**: Update documentation when making significant changes
+5. **Customize**: Adapt all documentation to your project's specific needs
+
+## Updating Documentation
+
+- Project documentation should be updated when goals, tech stack, or architecture changes
+- Technical standards should be updated when team conventions evolve
+- Always update INDEX.md when adding, removing, or significantly changing documentation
+```

package/dist/skills/flow-init/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: flow-init
+description: Initialize AI SDLC framework with intelligent project analysis and documentation generation
+argument-hint: [--standards-from=PATH]
+user-invocable: true
+---
+
+# Initialize AI SDLC Framework
+
+Initialize `.owflow/docs/` with intelligent project analysis and meaningful documentation generation based on actual codebase inspection.
+
+**NOTE**: This skill invokes other skills and subagents at specific phases. Use the **Task tool with `docs-operator` subagent** (subagent_type: `docs-operator`) for all docs-manager operations, and **Task tool** for project-analyzer. Use the **Skill tool** only for standards-discover (Phase 8, last phase). The Task tool returns control to this skill after completion; the Skill tool does not.
+
+## Phase Configuration
+
+| Phase | Subject                            | activeForm                       |
+| ----- | ---------------------------------- | -------------------------------- |
+| 1     | Pre-flight checks                  | Running pre-flight checks        |
+| 2     | Analyze project codebase           | Analyzing project codebase       |
+| 3     | Present findings & gather context  | Gathering project context        |
+| 4     | Select standards to initialize     | Selecting standards              |
+| 5     | Initialize documentation structure | Initializing documentation       |
+| 6     | Generate project documentation     | Generating project documentation |
+| 7     | Validate                           | Validating initialization        |
+| 8     | Discover coding standards          | Discovering coding standards     |
+
+**Task Tracking**: Before Phase 1, use `TaskCreate` for all phases (pending), then set sequential dependencies with `TaskUpdate addBlockedBy`. At each phase: `TaskUpdate` to `in_progress` → execute → `TaskUpdate` to `completed`. If skipped (e.g., user selects "Update existing"), mark skipped phases as `completed` with `metadata: {skipped: true}`.
+
+---
+
+## PHASE 1: Pre-flight Checks
+
+**If `--standards-from=PATH` is provided:**
+
+1. Resolve the path (absolute or relative to current working directory)
+2. Check if `PATH/.owflow/docs/standards/` exists. If not, inform the user and stop — the specified project doesn't have owflow standards initialized.
+3. Store the resolved standards source path for use in Phases 4 and 5.
+
+Check if `.owflow/` directory already exists.
+
+**If exists**, use question:
+
+- Options: "Backup and reinitialize", "Update existing documentation", "Cancel"
+- If "Backup": Create `.owflow.backup-$(date +%Y%m%d-%H%M%S)/` using Bash tool
+- If "Update": Skip to PHASE 6 (documentation generation only)
+- If "Cancel": Stop execution
+
+---
+
+## PHASE 2: Project Analysis
+
+Invoke `project-analyzer` subagent via the Task tool.
+
+Wait for completion. Store analysis results for use in Phases 3 and 6.
+
+---
+
+## PHASE 3: Present Findings & Gather Context
+
+**Step 1**: Present analysis results to the user (project type, primary language/framework, architecture, tech stack, conventions, strengths/opportunities).
+
+**Step 2**: Use question to confirm analysis accuracy. If corrections needed, collect them.
+
+**Step 3**: Gather additional context via question (adapt to project type):
+
+1. Project name (if not obvious)
+2. Project description (1-2 sentences)
+3. Primary goals (adapt question to new/existing/legacy project)
+4. Team context (optional)
+5. Special requirements (optional)
+
+**Step 4**: Ask which project documentation to generate using question (multi-select):
+
+- "Vision" — Project vision, goals, and purpose
+- "Roadmap" — Development roadmap and planned features
+- "Tech Stack" — Technology choices and rationale (ALWAYS selected, required)
+- "Architecture" — System architecture and design patterns (optional)
+
+Smart defaults based on `projectArchitectureType`:
+
+- Standard/Frontend-only/Backend-only: All selected
+- Monorepo/Umbrella: Only "Tech Stack" selected
+
+Store selections for Phase 6.
+
+---
+
+## PHASE 4: Select Standards to Initialize
+
+Before presenting options, explain to the user:
+
+- **What standards are**: Coding standards are documented conventions and best practices (naming, error handling, testing patterns, etc.) that guide consistent development across the project.
+- **Starting point**: If `--standards-from` was provided, standards come from the referenced project. Otherwise, the plugin includes generic built-in standards. Either way, they serve as a starting point and can be fully customized or extended later.
+
+**Determine available categories:**
+
+- **If `--standards-from` was provided**: Scan `PATH/.owflow/docs/standards/*/` to discover all available categories from the external project (may include custom categories beyond the baseline global/frontend/backend/testing).
+- **Otherwise**: Use built-in baseline categories (global, frontend, backend, testing).
+
+Calculate smart defaults based on analysis:
+
+- **Global**: Always recommended (if available)
+- **Frontend**: If frontend framework detected or projectArchitectureType includes frontend (if available)
+- **Backend**: If backend framework detected or projectArchitectureType includes backend (if available)
+- **Testing**: Always recommended (if available)
+
+Also scan `.owflow/docs/standards/*/` for any existing custom categories to include.
+
+Show smart defaults summary (noting the source: external project or built-in), then use question:
+
+- "Use smart defaults" → proceed with calculated defaults
+- "Customize selection" → show multi-select with all discovered categories + "Add custom category" option
+
+Custom categories: if user adds a new category, create the directory and include it in the selection.
+
+Store selection for Phase 5.
+
+---
+
+## PHASE 5: Initialize Documentation Structure
+
+**Invoke `docs-operator` subagent** via Task tool (subagent_type: `docs-operator`) with prompt:
+
+> "Initialize documentation structure. Standards selection: [array from Phase 4]. [If --standards-from was provided: Standards source path: [resolved path]/.owflow/docs/standards/. Copy standards from this external path instead of built-in defaults.] Only copy selected standard categories. Do NOT copy project templates — only create the project/ directory. Project documentation will be generated in Phase 6 with real content from project analysis. Create placeholder sections in INDEX.md for skipped categories."
+
+Wait for docs-operator to complete, then immediately proceed to Phase 6.
+
+---
+
+## PHASE 6: Generate Project Documentation
+
+**IMPORTANT**: Only generate docs selected in Phase 3.
+
+For each selected doc type, read the corresponding reference template:
+
+- Vision selected → Read `references/vision-templates.md`, select template by project type (new/existing/legacy)
+- Roadmap selected → Read `references/roadmap-templates.md`, select template by project type
+- Tech Stack (always) → Read `references/tech-stack-template.md`
+- Architecture selected → Read `references/architecture-template.md`
+
+Fill templates using:
+
+- Analysis report data (tech stack, age, structure)
+- User-provided context from Phase 3 (goals, users, requirements)
+- Auto-detected project characteristics
+
+Write each file to `.owflow/docs/project/`.
+
+---
+
+## PHASE 7: Validate
+
+**Step 1**: Invoke `docs-operator` subagent via Task tool (subagent_type: `docs-operator`) with prompt:
+
+> "Regenerate INDEX.md to include all newly created project documentation. Then verify AGENTS.md is properly integrated with .owflow/docs/ documentation."
+
+Wait for docs-operator to complete, then immediately continue with Step 2.
+
+**Step 2**: Run validation checks:
+
+- Verify INDEX.md exists
+- Verify tech-stack.md exists (required)
+- Verify selected docs exist
+- Verify selected standards directories exist
+- Verify AGENTS.md integration
+
+**Step 3**: Display comprehensive summary:
+
+- Project analysis results (type, language, framework, architecture)
+- Structure created (tree with check marks for created items)
+- Documentation status (which docs generated, which standards initialized)
+- Key findings (strengths, opportunities)
+- Next steps:
+  1. Review generated documentation
+  2. Customize for your team
+  3. Start development with `/work`
+  4. Keep documentation current
+
+---
+
+## PHASE 8: Discover Coding Standards
+
+Invoke the `standards-discover` skill via Skill tool with `--scope=full` to automatically discover coding standards from the project's config files, source code patterns, documentation, and external sources.
+
+> "Run standards discovery with --scope=full. This is being invoked as part of project initialization."
+
+The standards-discover skill handles its own user interaction (presenting findings by confidence tier, asking for approval). Let it run its full workflow — this is the last phase of init, so context handoff is fine here.
+
+After completion, display a brief summary of how many standards were discovered and applied.
+
+---
+
+## Error Handling Principles
+
+- If `.owflow/docs/` creation fails: check permissions, suggest manual creation
+- If project-analyzer fails: offer to proceed with manual input only
+- If docs-manager fails: offer retry (max 2 attempts), then manual instructions
+- Never auto-rollback — always ask user before destructive actions

package/dist/skills/flow-init/references/architecture-template.md

@@ -0,0 +1,45 @@
+# Architecture Document Template
+
+Optional documentation — only generate if user selected "Architecture" in Phase 3.
+
+```markdown
+# System Architecture
+
+## Overview
+[High-level description of system architecture]
+
+## Architecture Pattern
+**Pattern**: [From analysis - e.g., "Layered monolithic with REST API"]
+
+[Description of how the pattern is implemented]
+
+## System Structure
+
+### [Component 1]
+- **Location**: [From analysis - e.g., "src/api/"]
+- **Purpose**: [What it does]
+- **Key Files**: [List from analysis]
+
+### [Component 2]
+- **Location**: [From analysis]
+- **Purpose**: [What it does]
+- **Key Files**: [List from analysis]
+
+## Data Flow
+[Describe how data flows through the system]
+
+## External Integrations
+[List integrations found in analysis - databases, APIs, services]
+
+## Database Schema
+[If ORM detected, reference schema file location]
+
+## Configuration
+[How configuration is managed]
+
+## Deployment Architecture
+[If detected - Docker, K8s, cloud services]
+
+---
+*Based on codebase analysis performed [Date]*
+```