refactor: remove unused directories and enhance Claude Code integration (#60)

* chore: remove unused directories and simplify project structure

- Removed artifacts, openapi, and specs directories
- Updated all documentation to reflect simplified structure
- Streamlined project for better clarity and maintainability
- Moving to test-driven approach instead of spec files

* feat: add spec-feature Claude command for Gherkin specifications

- Created /spec-feature command to write Gherkin specs as GitHub issues
- Specs are now managed as GitHub issues instead of filesystem
- Issues created are ready for /implement-github-issue command
- Updated documentation to reflect new spec workflow
- Maintains spec-first approach without filesystem clutter

* docs: update changeset to include spec-feature command addition

* docs: refactor development guidelines and update implement-github-issue command

- Moved global coding standards and patterns to CLAUDE.md
- Added comprehensive testing requirements and troubleshooting
- Simplified implement-github-issue to reference CLAUDE.md
- Added branch naming conventions and commit format examples
- Better separation between project guidelines and command workflows

* docs: update changeset with comprehensive change details

* Update docs/PROCESS.md

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>

Author: sapientpants

.changeset/remove-unused-directories.md

@@ -0,0 +1,33 @@
+---
+'agentic-node-ts-starter': minor
+---
+
+Refactor project structure and enhance Claude Code integration
+
+## Removed Unused Directories
+
+- Removed `artifacts/` directory (unused)
+- Removed `openapi/` directory (unused)
+- Removed `specs/` directory (replaced with GitHub issues)
+
+## Claude Command Improvements
+
+- Added `/spec-feature` command to create Gherkin specs as GitHub issues
+- Enhanced `/implement-github-issue` command with comprehensive workflow
+- Removed deprecated `/analyze-and-fix-github-issue` command
+- Removed deprecated `/release` command (superseded by automated Changesets)
+
+## Documentation Refactoring
+
+- Moved global coding standards from commands to `CLAUDE.md`
+- Added comprehensive testing patterns and troubleshooting guides to `CLAUDE.md`
+- Updated `PROCESS.md` to reflect GitHub issue-based specifications
+- Updated `README.md` with correct workflow references
+- Fixed `CONTRIBUTING.md` references
+
+## Workflow Improvements
+
+- Specs now managed as GitHub issues instead of filesystem
+- Issues created with `/spec-feature` are ready for `/implement-github-issue`
+- Maintains spec-first approach without filesystem clutter
+- Clearer separation between project-wide guidelines and command-specific instructions

.claude/commands/analyze-and-fix-github-issue.md

@@ -0,0 +1,140 @@
+# Implement GitHub Issue
+
+You are about to implement GitHub issue: $ARGUMENTS
+
+## Implementation Workflow
+
+### 1. Analyze the Issue
+
+```bash
+gh issue view $ARGUMENTS
+```
+
+- Review the full issue description
+- If it contains Gherkin specs, parse acceptance criteria carefully
+- Identify non-goals and constraints
+- Note any technical requirements
+
+### 2. Research Codebase
+
+- Search for relevant existing code
+- Identify files needing modification
+- Look for similar patterns to maintain consistency
+- Review existing tests for patterns
+
+### 3. Plan Implementation
+
+Create a plan with:
+
+- Core functionality breakdown
+- Test strategy (unit + property-based)
+- Files to create/modify
+- Edge cases and risks
+
+### 4. Create Feature Branch
+
+```bash
+# Follow branch naming from CLAUDE.md
+git checkout -b <type>/<issue-number>-<description>
+# Example: feat/42-user-authentication
+```
+
+### 5. Implement Solution
+
+- Follow patterns in CLAUDE.md (validation, testing, imports)
+- Write clean, focused functions
+- Add TypeScript types and Zod validation
+- Document public APIs with JSDoc
+
+### 6. Write Tests
+
+Required test coverage:
+
+- **Unit tests** in `tests/*.spec.ts`
+- **Property-based tests** in `tests/*.property.spec.ts` for business logic
+- Test both success and failure cases
+- Verify edge cases
+
+### 7. Verify Quality
+
+```bash
+pnpm verify  # Runs all checks
+```
+
+### 8. Create Changeset
+
+```bash
+pnpm changeset
+# Select: patch (fixes), minor (features), major (breaking)
+```
+
+### 9. Commit Changes
+
+```bash
+git add .
+git commit -m "<type>: <description>
+
+<body-if-needed>
+
+Closes #<issue-number>"
+```
+
+### 10. Create Pull Request
+
+```bash
+git push -u origin <branch-name>
+
+gh pr create \
+  --title "<type>: <description>" \
+  --body "## Summary
+  <what-and-why>
+
+  ## Changes
+  - <list-changes>
+
+  ## Testing
+  - <how-tested>
+
+  Closes #<issue-number>" \
+  --assignee @me
+```
+
+### 11. Monitor CI
+
+```bash
+gh pr checks --watch
+```
+
+### 12. Address Feedback
+
+- Respond to review comments
+- Make requested changes
+- Re-verify after changes
+
+### 13. Merge PR
+
+```bash
+# After approval and passing checks
+gh pr merge --squash --delete-branch
+```
+
+## Key Points
+
+- **Follow coding standards** in CLAUDE.md
+- **Test thoroughly** - Unit + property-based tests required
+- **Use changesets** for version management
+- **Conventional commits** for clear history
+- **Quality first** - All checks must pass
+
+## Success Checklist
+
+Before completing:
+
+- [ ] All acceptance criteria met
+- [ ] Tests comprehensive (unit + property)
+- [ ] `pnpm verify` passes
+- [ ] Documentation updated
+- [ ] Changeset created
+- [ ] PR reviewed and approved
+
+See CLAUDE.md for detailed patterns, troubleshooting, and coding standards.