Metadata-Version: 2.2
Name: bisos.startAiActivity
Version: 0.11
Summary: bisos.startAiActivity: Install AI Collaborative Development Templates
Author: Mohsen Banan
Author-email: libre@mohsen.1.banan.byname.net
Maintainer: Mohsen Banan
Maintainer-email: libre@mohsen.1.banan.byname.net
License: AGPL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: bisos
Requires-Dist: bisos.b
Requires-Dist: bisos.common
Requires-Dist: bisos.pyDblock
Requires-Dist: setuptools==75.8.0
Requires-Dist: wheel==0.38.4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: summary

=====================================================================
bisos.startAiActivity: Install AI Collaborative Development Templates
=====================================================================

.. contents::
   :depth: 3
..

Overview
========

*bisos.startAiActivity* installs the ByStar AI collaborative development
template set (``CLAUDE.md``, ``AI-AGENTS.org``, ``AI-WORKFLOW.org``,
``AI-Activity.org``, ``AI-DevStatus.org``, ``AI-WorkPlan.org``) into any
project directory or git repo root, wiring it for collaborative
development with Claude Code.

bisos.startAiActivity is a python package that uses the
`PyCS-Framework <https://github.com/bisos-pip/pycs>`__. It provides the
``startAiActivity.cs`` command for installing and managing AI
collaborative development templates.

.. _table-of-contents:

Table of Contents TOC
=====================

-  `Overview <#overview>`__
-  `Part of BISOS — ByStar Internet Services Operating
   System <#part-of-bisos--bystar-internet-services-operating-system>`__
-  `bisos.startAiActivity is a Command-Only PyCS
   Facility <#bisosstartaiactivity-is-a-command-only-pycs-facility>`__
-  `Post-Installation Setup <#post-installation-setup>`__
-  `Installation <#installation>`__

   -  `Installation With pip <#installation-with-pip>`__
   -  `Installation With pipx <#installation-with-pipx>`__
   -  `Post-Installation Basic
      Testing <#post-installation-basic-testing>`__

-  `Usage <#usage>`__

   -  `Set Templates Base Directory <#set-templates-base-directory>`__
   -  `Install Templates Into a
      Project <#install-templates-into-a-project>`__
   -  `Install a Subproject Overlay <#install-a-subproject-overlay>`__
   -  `Skills <#skills>`__
   -  `Suspend and Resume AI
      Collaboration <#suspend-and-resume-ai-collaboration>`__
   -  `Remove AI Collaboration Files <#remove-ai-collaboration-files>`__

-  `Key Files <#key-files>`__

   -  ```py3/bin/startAiActivity.cs`` <#py3binstartaiactivitycs>`__
   -  ```py3/bisos/startAiActivity/updateDblock.py`` <#py3bisosstartaiactivityupdatedblockpy>`__
   -  ```py3/bisos/startAiActivity/dblock_particulars.py`` <#py3bisosstartaiactivitydblock_particularspy>`__
   -  `PyPi and Github Packaging <#pypi-and-github-packaging>`__

-  `Testing <#testing>`__
-  `Documentation and Blee-Panels <#documentation-and-blee-panels>`__

   -  `bisos.startAiActivity
      Blee-Panels <#bisosstartaiactivity-blee-panels>`__

-  `Support <#support>`__
-  `Planned Improvements <#planned-improvements>`__

Part of BISOS — ByStar Internet Services Operating System
=========================================================

Layered on top of Debian, **BISOS** (By\* Internet Services Operating
System) is a unified and universal framework for developing both
internet services and software-service continuums that use internet
services. See `Bootstrapping ByStar, BISOS and
Blee <https://github.com/bxGenesis/start>`__ for information about
getting started with BISOS.

**BISOS** is a foundation for **The Libre-Halaal ByStar Digital
Ecosystem** which is described as a cure for losses of autonomy and
privacy in a book titled: `Nature of
Polyexistentials <https://github.com/bxplpc/120033>`__

*bisos.startAiActivity* is part of BISOS. It is a standalone package
that can be used independently of the full BISOS environment.

bisos.startAiActivity is a Command-Only PyCS Facility
=====================================================

bisos.startAiActivity is a command-line tool. It is a PyCS single-unit
command service. PyCS is a framework that converges development of CLI
tools and services. PyCS is an alternative to FastAPI, Typer and Click.

bisos.startAiActivity uses the PyCS-Framework to:

#. Install AI collaborative development templates (symlinks and
   safe-copies) into any project directory or git repo root.
#. Expand ``b:ai:file/particulars`` org-mode dynamic blocks in installed
   files using pure Python, without requiring Emacs or ``bx-dblock``.
#. Manage persistent user-config parameters (e.g. ``templates`` base
   path) via ``~/.config/bisos/startAiActivity.cs/``.

The core of PyCS-Framework is the *bisos.b* package (the
PyCS-Foundation). See `bisos.b <https://github.com/bisos-pip/b>`__ for
an overview.

Post-Installation Setup
=======================

After installing, configure the templates base directory. If
``/bisos/apps/defaults/ai-templates`` exists on your system it is used
as the default automatically. Otherwise, set it explicitly:

.. code:: bash

   startAiActivity.cs -i userConfig_set --parName=templates --parValue=/path/to/ai-templates

Verify the setting:

.. code:: bash

   startAiActivity.cs -i userConfig_get --parName=templates

The AI templates are maintained at:
https://github.com/bisos/defaults/tree/master/ai-templates

Installation
============

The sources for the bisos.startAiActivity pip package are maintained at:
https://github.com/bisos-pip/startAiActivity.

The bisos.startAiActivity pip package is available at PYPI as
https://pypi.org/project/bisos.startAiActivity

You can install bisos.startAiActivity with pip or pipx.

Installation With pip
---------------------

If you need access to bisos.startAiActivity as a python module, you can
install it with pip:

.. code:: bash

   pip install bisos.startAiActivity

Installation With pipx
----------------------

If you only need access to bisos.startAiActivity on command-line, you
can install it with pipx:

.. code:: bash

   pipx install bisos.startAiActivity

The following commands are made available:

-  ``startAiActivity.cs`` — installs AI collaborative development
   templates

Post-Installation Basic Testing
-------------------------------

After installation, run:

.. code:: bash

   startAiActivity.cs
   startAiActivity.cs -i userConfig_get --parName=templates

Usage
=====

Set Templates Base Directory
----------------------------

.. code:: bash

   startAiActivity.cs -i userConfig_set --parName=templates --parValue=/path/to/ai-templates

Install Templates Into a Project
--------------------------------

Install into the current directory:

.. code:: bash

   startAiActivity.cs -i initiate --activity=bisos-pip

Install at the git repo root:

.. code:: bash

   startAiActivity.cs -i initiate --root=repo --activity=bisos-pip

Available activities match subdirectories under the templates base (e.g.
``bisos-pip``, ``bisos-core``, ``xu-single``, ``blee-panels``,
``lcnt``). Run ``startAiActivity.cs -i examples`` to see all available
activities.

``initiate`` installs the following into the target directory: symlinks
for the constant files (``CLAUDE.md``, ``AI-AGENTS.org``,
``AI-WORKFLOW.org``, ``AI-Activity.org``); safe-copies of the editable
files (``AI-DevStatus.org``, ``AI-WorkPlan.org``, with
``b:ai:file/particulars`` dblocks expanded); and symlinks under
``.claude/`` for ``settings.json``, ``commands/``, and ``skills/`` (when
the activity ships a ``_skills/`` directory). See the **Skills**
subsection below.

Install a Subproject Overlay
----------------------------

For repos with nested loosely-related subprojects that each want their
own work plan and dev status without duplicating the invariant files
(``AI-AGENTS.org``, ``AI-WORKFLOW.org``, ``.claude/``), use
``initiateSub``:

.. code:: bash

   startAiActivity.cs -i initiateSub --activity=bisos-pip

This installs only the subproject-specific state — a slim ``CLAUDE.md``
(symlinked to ``mother/initiateSub/CLAUDE.md``), ``AI-Activity.org``
symlink, and safe-copies of ``AI-DevStatus.org`` and
``AI-WorkPlan.org``. It does NOT install ``AI-AGENTS.org``,
``AI-WORKFLOW.org``, or ``.claude/`` — those are inherited from an
ancestor directory via Claude Code's ``CLAUDE.md`` walk-up.

**Preconditions** (``initiateSub`` refuses if either fails):

#. An ancestor directory must have been ``initiate``-d already
   (``initiateSub`` walks up looking for a startAiActivity-signature
   ``CLAUDE.md`` symlink).
#. The target directory must not already have a ``CLAUDE.md``.

The ``--activity`` flag is required — a subproject may be a different
activity from its parent (e.g., a ``blee-panels`` subproject inside a
``bisos-pip`` repo).

Nested ``initiateSub`` is supported: a subproject's ``CLAUDE.md``
satisfies the walk-up precondition for a sub-subproject.

``aiSuspend`` / ``aiResume`` / ``deClaudify`` all work correctly on
subproject overlays. ``aiResume`` detects sub vs. base mode from the
stashed ``CLAUDE.md.dormant`` symlink target.

Skills
------

When an activity ships a ``_skills/`` directory at its templates root,
``initiate`` symlinks it to ``.claude/skills/`` alongside the other
``.claude/`` entries. Claude Code discovers those skills automatically
and loads them on demand when the current task calls for them.

**Skills** are self-contained, filesystem-based packages of
task-specific instructions. Each skill is a folder containing a
``SKILL.md`` file whose front-matter description tells Claude when to
consult the full file. This lets a repo carry deep procedural knowledge
(how to write a CS command, how to author a Blee panel, how to release
to PyPI) without loading that content on every session — the short
descriptions sit in context by default, and Claude reads the full skill
only when it matches the task at hand.

The ``bisos-pip`` activity currently ships five skills:

-  ``writing-cs-commands`` — authoring ``cs.Cmnd`` subclasses (params,
   args, classHead dblock, common patterns).
-  ``dblock-authoring`` — working with poly-dblock ``begin:`` blocks,
   the ``csuListProc`` pattern, and dblock-based inline unit tests.
-  ``readme-authorship`` — writing ``README.org`` (repo root — the only
   authored README; ``py3/README.rst`` is generated by
   ``pypiProc.sh -i fullPrep`` and must never be hand-edited).
-  ``blee-panel-authorship`` — the standard ``fullUsagePanel-en.org``
   skeleton and dblock content policy.
-  ``bisos-pip-release`` — end-to-end PyPI release checklist (linters,
   packaging, Test-PyPI trial, upload).

To author a new skill, add a folder under the appropriate templates
directory:

-  ``mother/_skills/<name>/SKILL.md`` — available to every activity
-  ``<activity>/_skills/<name>/SKILL.md`` — activity-specific

Each ``SKILL.md`` starts with YAML front-matter (``---``-delimited)
containing ``name:`` and ``description:`` fields. The description drives
when Claude loads the skill; write it as a concrete trigger ("Use when
writing or modifying a PyCS ``cs.Cmnd`` subclass") rather than a topic
label.

Suspend and Resume AI Collaboration
-----------------------------------

When AI collaboration on a project needs to be paused temporarily, use
``aiSuspend`` to enter a dormant state and ``aiResume`` to restore it.

``aiSuspend`` removes the constant symlinks (``CLAUDE.md``,
``AI-AGENTS.org``, ``AI-WORKFLOW.org``, ``AI-Activity.org``) and the
``.claude/`` entries, and renames the editable files
``AI-DevStatus.org`` and ``AI-WorkPlan.org`` to ``.dormant`` suffixes so
that the collaboration state survives.

.. code:: bash

   startAiActivity.cs -i aiSuspend

``aiResume`` restores the ``.dormant`` files, re-installs the symlinks,
and re-installs ``.claude/``. The activity is inferred from the
``AI-Activity.org`` symlink target or from the ``Activity:`` header
inside ``AI-WorkPlan.org``.

.. code:: bash

   startAiActivity.cs -i aiResume

Both commands operate on the current directory.

Remove AI Collaboration Files
-----------------------------

To permanently remove all AI collaboration files from a project, use
``deClaudify``. Unlike ``aiSuspend``, this is irreversible — it deletes
the editable ``AI-DevStatus.org`` and ``AI-WorkPlan.org`` files along
with the symlinks and ``.claude/`` entries.

.. code:: bash

   startAiActivity.cs -i deClaudify

The command is safe: symlinks are only removed if they are actually
symlinks, and copied files are only removed if they are regular files.
Anything a user has created or converted manually is left intact.

Key Files
=========

An overview of the relevant files of the bisos.startAiActivity package:

``py3/bin/startAiActivity.cs``
------------------------------

The main CS-MU (Command-Services Multi-Unit). Provides the ``initiate``,
``aiSuspend``, ``aiResume``, ``deClaudify``, ``userConfig_get``, and
``userConfig_set`` commands. Uses ``bisos.b.userConfig_csu`` for
persistent parameter management.

``py3/bisos/startAiActivity/updateDblock.py``
---------------------------------------------

General dblock dispatch engine. Handlers register under a signature
string via ``registerHandler(sig, fn)``. ``expandAll(filePath)`` does a
single-pass regex substitution over the file, dispatching each
``begin: <signature>`` block to its registered handler.

``py3/bisos/startAiActivity/dblock_particulars.py``
---------------------------------------------------

Self-registering handler for the ``b:ai:file/particulars`` dblock
signature. Derives the ``activity`` from the ``AI-Activity.org`` symlink
and builds the companion-docs list by scanning the directory.

PyPi and Github Packaging
-------------------------

All bisos-pip repos in the https://github.com/bisos-pip github
organization follow the same structure. They all have
`setup.py <./setup.py>`__ files driven by
`pypiProc.sh <./pypiProc.sh>`__.

Testing
=======

An end-to-end verification harness lives at ``py3/test/verify.sh``. It
exercises every command in the ``startAiActivity.cs`` surface —
user-config read/write, ``initiate``, ``deClaudify``, ``aiSuspend`` /
``aiResume`` (with base-mode detection), and ``initiateSub`` (both the
positive case within the repo and a negative case in an isolated
``/tmp/`` dir that expects a ``EH_Problem_UsageError`` refusal).

Run it as:

.. code:: bash

   cd py3/test
   ./verify.sh

The shebang is ``#!/bin/bash -i`` — this makes the shell interactive, so
``~/.bashrc`` runs its full body and defines the ``lpDo`` alias (from
ByStar's ``_opDo`` convention) used throughout the script for uniform
logging.

The harness starts from a clean state and leaves a clean state — the
test directory contains only ``verify.sh`` itself before and after a
successful run. Exit code 0 indicates all steps behaved as expected
(including the intended refusal in the negative case).

Documentation and Blee-Panels
=============================

bisos.startAiActivity is part of ByStar Digital Ecosystem
http://www.by-star.net.

This module's primary documentation is in the form of Blee-Panels.
Additional information is also available in:
http://www.by-star.net/PLPC/180047

bisos.startAiActivity Blee-Panels
---------------------------------

bisos.startAiActivity Blee-Panels are in the ``./panels`` directory.
From within Blee and BISOS these panels are accessible under the Blee
"Panels" menu.

See
`file:./panels/bisos.startAiActivity/_nodeBase_/fullUsagePanel-en.org <./panels/bisos.startAiActivity/_nodeBase_/fullUsagePanel-en.org>`__
for a starting point.

Support
=======

| For support, criticism, comments and questions; please contact the
  author/maintainer
| `Mohsen Banan <http://mohsen.1.banan.byname.net>`__ at:
  http://mohsen.1.banan.byname.net/contact

Planned Improvements
====================

-  Upload to PyPI and test as pipx install
-  Write fullUsagePanel-en.org Blee-Panel
