@logickernel/agileflow 0.16.1 → 0.17.1

package/README.md

@@ -2,63 +2,59 @@
 
 # AgileFlow
 
-In today's fast-paced software development landscape, maintaining clarity, consistency, and efficiency in the release process is essential. AgileFlow is a streamlined yet powerful versioning system designed for software teams of all sizes and projects of any scale.
-
-AgileFlow enforces Semantic Versioning and integrates seamlessly with your CI/CD pipeline to ensure a structured, efficient, and predictable development lifecycle. **All versions are calculated from the main branch's commit history** using [Conventional Commits](https://www.conventionalcommits.org/), ensuring consistent versioning and release notes. Whether for small projects or large-scale deployments, AgileFlow simplifies versioning and release management.
+AgileFlow reads your commit history and automatically creates a semantic version tag on every merge to main. Your build and deploy pipelines then trigger on the tag — keeping versioning completely separate from everything else.
 
 ![AgileFlow workflow example diagram](./media/diagram.jpg)
 
-AgileFlow works with your CI/CD engine to **automatically create a new version tag** every time there's a merge into the main branch. Your existing build and deploy pipelines then trigger on tag creation, creating a clean separation between versioning and release processes. This decoupled architecture means AgileFlow focuses solely on versioning, while your build and deploy workflows remain independent.
+No config files. No servers. Versions are calculated from your [Conventional Commits](https://www.conventionalcommits.org/) and pushed as annotated git tags.
 
 ---
 
 ## Quick Start
 
-Install the tool
+Preview your next version in any git repository:
 
 ```bash
-npm install -g @logickernel/agileflow
+npx @logickernel/agileflow
 ```
 
-### Preview Your Next Version
-
-```bash
-agileflow
 ```
+Commits since current version (3):
+  a1b2c3d feat: add dark mode
+  d4e5f6a fix: resolve login timeout
+  7g8h9i0 docs: update README
 
-### Create a Version Tag
+Current version: v1.4.2
+New version:     v1.5.0
 
+Changelog:
 
-**Push to Remote Git Repository:**
-```bash
-agileflow push
-```
-
-#### CD/CI
+### Features
+- add dark mode
 
-**GitHub Actions:**
-```bash
-agileflow github
+### Bug fixes
+- resolve login timeout
 ```
 
-**GitLab CI:**
-```bash
-agileflow gitlab
-```
-
-**Learn More**: [Getting Started Guide](./docs/getting-started.md) • [CLI Reference](./docs/cli-reference.md)
+This is read-only — it never creates tags or modifies anything.
 
 ---
 
 ## CI/CD Integration
 
-AgileFlow uses a **two-step decoupled approach**:
+AgileFlow uses a **decoupled two-step approach**:
 
-### Step 1: Version Creation (AgileFlow)
+1. **Versioning** — AgileFlow runs on merge to main and creates a version tag
+2. **Release** — Your existing build and deploy pipelines trigger on the tag
+
+```
+Merge to main → AgileFlow → Tag v1.5.0 → Your build/deploy
+```
 
-Create a workflow that runs AgileFlow when code is merged to main:
+### GitHub Actions
+
+`.github/workflows/version.yml`:
 
-**GitHub Actions** (`.github/workflows/version.yml`):
 ```yaml
 name: Version
 on:
@@ -83,16 +79,11 @@ jobs:
         run: npx @logickernel/agileflow github
 ```
 
-**GitLab CI** (`.gitlab-ci.yml`):
-
-For a job tagged with `agileflow` for a GitLab Runner:
+Requires an `AGILEFLOW_TOKEN` secret — a Personal Access Token with `Contents: Read and write` permission.
 
-```yaml
-include:
-  - remote: https://code.logickernel.com/tools/agileflow/-/raw/main/.gitlab-ci.yml
-```
+### GitLab CI
 
-Or manually:
+`.gitlab-ci.yml`:
 
 ```yaml
 agileflow:
@@ -104,114 +95,50 @@ agileflow:
     - if: '$CI_COMMIT_BRANCH == "main"'
 ```
 
-### Step 2: Build & Deploy (Your Pipelines)
-
-Configure your existing build and deploy pipelines to trigger on tag creation. When AgileFlow creates a version tag (e.g., `v1.2.3`), your CI/CD platform triggers your release workflow. Use the tag name as the version identifier for your builds and deployments.
-
-**Learn More**: [Installation Guide](./docs/installation.md) for detailed setup instructions and examples.
-
-### Benefits of Decoupled Architecture
-
-- **Separation of concerns** — Versioning is independent from build/deploy
-- **Flexibility** — Hook any process to tag creation
-- **Reusability** — Same build pipeline works for any version
-- **Simplicity** — Each pipeline has a single responsibility
-
-**Learn More**: [Installation Guide](./docs/installation.md) • [Configuration](./docs/configuration.md)
-
----
-
-## Conventional Commits
+Requires an `AGILEFLOW_TOKEN` CI/CD variable — a Project Access Token with `api` scope and `Maintainer` role.
 
-AgileFlow uses [Conventional Commits](https://www.conventionalcommits.org/) to automatically determine version bumps and generate release notes. Commit messages follow a structured format that encodes the intent of each change:
+### Other platforms
 
-```text
-type(scope): description
+```bash
+agileflow push           # creates tag and pushes to origin
+agileflow push upstream  # pushes to a different remote
 ```
 
-The commit type (`feat`, `fix`, `perf`, etc.) indicates what kind of change was made, while the optional scope identifies the area affected. Breaking changes are marked with `!` or a `BREAKING CHANGE:` footer.
-
-**Learn More**: [Conventional Commits Guide](./docs/conventional-commits.md)
-
 ---
 
-## Release Management
-
-### Automatic Versioning
+## Conventional Commits
 
-Each merge to main triggers automatic version generation based on commit types. See the [Version Calculation](#version-calculation) table below for details on how versions are bumped in 0.x.x vs 1.0.0+.
+AgileFlow determines the version bump from commit types:
 
-New projects start at **v0.0.0** and automatically increment based on commits. AgileFlow will keep automatically generating versions as you develop (0.0.1, 0.0.2, 0.1.0, etc.). When your product has reached maturity and you have a stable API ready for production, create version 1.0.0 manually.
+| Commit | Example | Before v1.0.0 | v1.0.0 and after |
+|--------|---------|---------------|------------------|
+| Breaking change | `feat!: redesign API` | minor bump | major bump |
+| `feat` | `feat: add login` | minor bump | minor bump |
+| `fix` | `fix: resolve crash` | patch bump | patch bump |
+| Everything else | `docs: update README` | no bump | no bump |
 
-### Version 1.0.0 — First Stable Release
+The highest-priority bump across all commits since the last tag wins. If no bump-triggering commits exist, AgileFlow exits without creating a tag.
 
-Version 1.0.0 represents your first stable API and marks the transition from initial development to a stable, production-ready release. This version **must be created manually** when your team decides the API is stable and ready for production use.
+### v1.0.0 — First stable release
 
-Create it when ready:
+New projects start at `v0.0.0`. AgileFlow increments automatically from there. When your API is stable and ready for production, create `v1.0.0` manually:
 
 ```bash
 git tag -a v1.0.0 -m "First stable release"
 git push origin v1.0.0
 ```
 
-After 1.0.0, AgileFlow continues automatic versioning with standard semantic versioning rules: features bump minor, fixes bump patch, and breaking changes bump major.
-
-
-**Learn More**: [Release Management Guide](./docs/release-management.md)
-
----
-
-## Version Calculation
-
-AgileFlow analyzes commits since the last version tag to determine the appropriate version bump:
-
-| Commit Type | Example | Changelog | 0.x.x | 1.0.0+ |
-|-------------|---------|-----------|-------|--------|
-| Breaking change | `feat!: redesign API` | Add entry | **Minor** (0.1.0 → 0.2.0) | **Major** (1.0.0 → 2.0.0) |
-| Feature | `feat: add login` | Add entry | **Minor** | **Minor** |
-| Fix | `fix: resolve crash` | Add entry | **Patch** | **Patch** |
-| Chore | `chore: update dependencies` | **No** entry | No bump | No bump |
-| Everything else | `docs: update README` | Add entry | No bump | No bump |
-
----
-
-## Core Principles
-
-### Main Branch Strategy
-
-The main branch is the single source of truth for all releases:
-
-- **Single Version Sequence** — All versions created from the same branch
-- **Simplified Workflow** — No release branches needed
-- **Consistent History** — All releases share the same commit history
-- **Easy Rollbacks** — Deploy any previous version tag
-
-### Version-Centric Deployments
-
-Every environment runs the same immutable version:
-
-```
-Tag v1.2.3 ──▶ Build ──▶ Staging
-                    ──▶ Production
-                    ──▶ Any environment
-```
-
-**Learn More**: [Branching Strategy](./docs/branching-strategy.md) • [Version-Centric CI/CD](./docs/version-centric-cicd.md)
+After `v1.0.0`, breaking changes bump the major version.
 
 ---
 
 ## Documentation
 
-| Guide | Description |
-|-------|-------------|
-| [Getting Started](./docs/getting-started.md) | Quick start for new users |
-| [Installation](./docs/installation.md) | Setup for GitHub Actions and GitLab CI |
-| [CLI Reference](./docs/cli-reference.md) | Command-line options and usage |
-| [Configuration](./docs/configuration.md) | Environment variables and options |
-| [Conventional Commits](./docs/conventional-commits.md) | Commit message formatting |
-| [Branching Strategy](./docs/branching-strategy.md) | Development workflow |
-| [Version-Centric CI/CD](./docs/version-centric-cicd.md) | Pipeline methodology |
-| [Release Management](./docs/release-management.md) | Managing releases effectively |
-| [Migration Guide](./docs/migration-guide.md) | Transitioning from other approaches |
-| [Best Practices](./docs/best-practices.md) | Recommended patterns |
-| [Troubleshooting](./docs/troubleshooting.md) | Common issues and solutions |
+| | |
+|-|-|
+| [Getting Started](./docs/start-here/getting-started.md) | Run locally, understand the output, first CI setup |
+| [GitHub Actions](./docs/guides/github-actions.md) | Token setup, workflow files, troubleshooting |
+| [GitLab CI](./docs/guides/gitlab-ci.md) | Token setup, pipeline config, troubleshooting |
+| [Other CI/CD](./docs/guides/other-ci.md) | Git-push integration for any platform |
+| [CLI Reference](./docs/reference/cli.md) | All commands and options |
+| [Conventional Commits](./docs/reference/conventional-commits.md) | Commit format and changelog behavior |

package/docs/guides/github-actions.md

@@ -0,0 +1,110 @@
+# GitHub Actions
+
+Two workflows: one that runs AgileFlow on push to main and creates a version tag, and one that triggers on that tag to build and deploy.
+
+---
+
+## Step 1: Create an access token
+
+1. Go to **Settings → Developer settings → Personal access tokens → Fine-grained tokens**
+2. Click **Generate new token**
+3. Set:
+   - **Name**: `AgileFlow`
+   - **Repository access**: your repository
+   - **Permissions**: `Contents: Read and write`
+4. Copy the token
+
+## Step 2: Add the token as a secret
+
+1. In your repository: **Settings → Secrets and variables → Actions**
+2. Click **New repository secret**
+3. Name: `AGILEFLOW_TOKEN`, value: your token
+
+## Step 3: Create the versioning workflow
+
+`.github/workflows/version.yml`:
+
+```yaml
+name: Version
+on:
+  push:
+    branches: [main]
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Create version tag
+        env:
+          AGILEFLOW_TOKEN: ${{ secrets.AGILEFLOW_TOKEN }}
+        run: npx @logickernel/agileflow github
+```
+
+`fetch-depth: 0` is required — without it, AgileFlow can only see a shallow clone and cannot find the last version tag.
+
+## Step 4: Create the release workflow
+
+`.github/workflows/release.yml`:
+
+```yaml
+name: Release
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
+
+      - name: Build
+        run: |
+          docker build -t myapp:$VERSION .
+          docker push myapp:$VERSION
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - name: Deploy
+        run: kubectl set image deployment/myapp myapp=myapp:$VERSION
+```
+
+---
+
+## How it works end to end
+
+1. You push a `feat:` commit to main
+2. The `version` workflow runs AgileFlow, which creates tag `v1.5.0` via the GitHub API
+3. The tag push triggers the `release` workflow
+4. Your build runs with `VERSION=v1.5.0`
+
+If no bump is needed (all commits are `chore`, `docs`, etc.), AgileFlow exits without creating a tag, and the release workflow never runs.
+
+---
+
+## Troubleshooting
+
+**"AGILEFLOW_TOKEN not set"** — The secret is missing or not passed via `env:`. Verify the secret exists and the `env:` block is present in the step.
+
+**"Resource not accessible by integration" / 403** — The token lacks `Contents: Read and write` permission. Regenerate with the correct scope.
+
+**"Bad credentials" / 401** — The token has expired or was revoked. Regenerate and update the secret.
+
+**Tag created but release workflow didn't run** — Check that the release workflow trigger is `push: tags: ['v*']`, not `push: branches: [main]`.
+
+**"Current version: none"** — `fetch-depth: 0` is missing from the checkout step. AgileFlow cannot see the tag history in a shallow clone.

package/docs/guides/gitlab-ci.md

@@ -0,0 +1,128 @@
+# GitLab CI
+
+One pipeline job creates the version tag on push to main. A separate pipeline (triggered by the tag) builds and deploys.
+
+---
+
+## Step 1: Create an access token
+
+**Recommended: Project Access Token**
+
+1. Go to project **Settings → Access tokens**
+2. Create:
+   - **Name**: `AgileFlow`
+   - **Role**: `Maintainer`
+   - **Scopes**: `api`
+3. Copy the token
+
+**Alternative: Personal Access Token**
+
+1. Go to user **Settings → Access tokens**
+2. Create with `api` scope
+3. Copy the token
+
+## Step 2: Add the token as a CI/CD variable
+
+1. Go to project **Settings → CI/CD → Variables**
+2. Add:
+   - **Key**: `AGILEFLOW_TOKEN`
+   - **Value**: your token
+   - **Flags**: Protected, Masked
+
+## Step 3: Configure your pipeline
+
+`.gitlab-ci.yml`:
+
+```yaml
+stages:
+  - version
+  - build
+  - deploy
+
+# Runs on push to main — creates the version tag
+agileflow:
+  stage: version
+  image: node:20
+  script:
+    - npm install -g @logickernel/agileflow
+    - agileflow version
+    - agileflow gitlab
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+# Runs when a version tag is created — builds the release
+build:
+  stage: build
+  script:
+    - docker build -t myapp:$CI_COMMIT_TAG .
+    - docker push myapp:$CI_COMMIT_TAG
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
+
+# Runs when a version tag is created — deploys to staging automatically
+deploy-staging:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:$CI_COMMIT_TAG
+  environment:
+    name: staging
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
+
+# Runs when a version tag is created — deploys to production manually
+deploy-production:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:$CI_COMMIT_TAG
+  environment:
+    name: production
+  when: manual
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
+```
+
+The `agileflow version` line before `agileflow gitlab` is optional but useful for confirming which version of the tool is running when troubleshooting.
+
+---
+
+## How it works end to end
+
+1. You push a `feat:` commit to main
+2. The `agileflow` job runs and creates tag `v1.5.0` via the GitLab API
+3. GitLab starts a new pipeline for the tag
+4. `build` and `deploy-*` jobs run with `CI_COMMIT_TAG=v1.5.0`
+
+If no bump is needed (all commits are `chore`, `docs`, etc.), AgileFlow exits without creating a tag, and no release pipeline runs.
+
+---
+
+## Shallow clone behavior
+
+GitLab CI uses shallow clones by default (`GIT_DEPTH: 20`). AgileFlow handles this by reading tag metadata directly from the remote via `git ls-remote` instead of relying on a full fetch. This works without any extra configuration in most cases.
+
+If you see `Current version: none` despite having version tags, set a larger depth or disable shallow cloning:
+
+```yaml
+variables:
+  GIT_DEPTH: 0  # fetch full history
+```
+
+---
+
+## Troubleshooting
+
+**"AGILEFLOW_TOKEN not set"** — The CI/CD variable is missing. Verify it exists under **Settings → CI/CD → Variables**.
+
+**"403 Forbidden"** — The token lacks `api` scope or `Maintainer` role. Regenerate with the correct permissions.
+
+**"401 Unauthorized"** — The token has expired. Regenerate and update the variable.
+
+**Tag created but no build pipeline** — Check that build/deploy rules use `$CI_COMMIT_TAG =~ /^v/`, not `$CI_COMMIT_BRANCH`.
+
+**`Current version: none` on first run** — Expected if you have no version tags yet. AgileFlow will start from `v0.0.0`. Create a manual tag first if you need a specific starting point:
+```bash
+git tag -a v1.0.0 -m "First stable release"
+git push origin v1.0.0
+```
+
+**Both main and tag pipelines run at the same time** — This is normal. The main pipeline creates the tag; the tag triggers the release pipeline. They are independent.

package/docs/guides/other-ci.md

@@ -0,0 +1,93 @@
+# Other CI/CD Platforms
+
+For platforms without a native AgileFlow integration, use the `push` command. It creates an annotated git tag and pushes it to a git remote using standard git commands and your existing credentials.
+
+```bash
+agileflow push           # push to origin (default)
+agileflow push upstream  # push to a different remote
+```
+
+---
+
+## Basic setup
+
+Configure git identity and credentials in your CI environment, then run:
+
+```bash
+git config user.name "CI Bot"
+git config user.email "ci@example.com"
+npx @logickernel/agileflow push
+```
+
+Then configure your CI platform to trigger build/deploy pipelines on tag creation.
+
+---
+
+## Examples
+
+### Jenkins
+
+```groovy
+pipeline {
+  agent any
+  stages {
+    stage('Version') {
+      when { branch 'main' }
+      steps {
+        sh '''
+          git config user.name "Jenkins"
+          git config user.email "jenkins@example.com"
+          npx @logickernel/agileflow push
+        '''
+      }
+    }
+  }
+}
+```
+
+### Bitbucket Pipelines
+
+```yaml
+pipelines:
+  branches:
+    main:
+      - step:
+          name: Version
+          script:
+            - git config user.name "Bitbucket Pipelines"
+            - git config user.email "ci@example.com"
+            - npx @logickernel/agileflow push
+```
+
+### CircleCI
+
+```yaml
+jobs:
+  version:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run:
+          name: Create version tag
+          command: |
+            git config user.name "CircleCI"
+            git config user.email "ci@example.com"
+            npx @logickernel/agileflow push
+
+workflows:
+  main:
+    jobs:
+      - version:
+          filters:
+            branches:
+              only: main
+```
+
+---
+
+## Requirements
+
+- Git credentials must be configured for push access to the remote
+- The CI runner must have network access to the git remote
+- Your platform must support triggering pipelines on tag events

package/docs/index.md

@@ -0,0 +1,58 @@
+# AgileFlow
+
+AgileFlow reads your commit history, calculates the next semantic version, and creates a git tag — automatically, on every push to main.
+
+No config files. No servers. Just commits and tags.
+
+```bash
+npx @logickernel/agileflow
+```
+
+```
+Commits since current version (3):
+  a1b2c3d feat: add dark mode
+  d4e5f6a fix: resolve login timeout
+  7g8h9i0 docs: update README
+
+Current version: v1.4.2
+New version:     v1.5.0
+
+Changelog:
+
+### Features
+- add dark mode
+
+### Bug fixes
+- resolve login timeout
+```
+
+---
+
+## How it works
+
+1. On push to main, AgileFlow analyzes commits since the last version tag
+2. It calculates the next version using [Conventional Commits](./reference/conventional-commits.md)
+3. It creates an annotated git tag with the changelog as the tag message
+4. Your build and deploy pipelines trigger on the tag
+
+This is the **decoupled architecture**: versioning is a separate concern from building and deploying.
+
+```
+Push to main → AgileFlow → Tag v1.5.0 → Your build/deploy pipelines
+```
+
+---
+
+## Documentation
+
+### Start Here
+- [Getting Started](./start-here/getting-started.md) — Run AgileFlow locally, understand the output, set up your first CI integration
+
+### Guides
+- [GitHub Actions](./guides/github-actions.md) — Full setup for GitHub repositories
+- [GitLab CI](./guides/gitlab-ci.md) — Full setup for GitLab repositories
+- [Other CI/CD](./guides/other-ci.md) — Git-push based integration for any platform
+
+### Reference
+- [CLI Reference](./reference/cli.md) — All commands and options
+- [Conventional Commits](./reference/conventional-commits.md) — Commit format and version impact